🧠 NeoGraph.AI — Generative Knowledge Web (GKW)

Transform static documents and complex concepts into interactive AI-powered 3D knowledge graphs for faster learning, reasoning, and discovery.

🚀 Live Demo • 📖 AI Studio • 🐛 Report Bug • ✨ Request Feature

---

📚 Table of Contents

• About The Project
• Key Features
• Tech Stack
• System Architecture
• Getting Started
• Project Structure
• API Documentation
• Model / Algorithm Details
• Screenshots / Demo
• Use Cases
• Roadmap
• Contributing
• License
• Author
• Acknowledgements

---

🔍 About The Project

NeoGraph.AI is a generative knowledge visualization platform that converts dense academic, scientific, and professional content into dynamic 3D graph structures. It was built to solve the problem of static, linear learning by helping users explore entities, relationships, pathways, simulations, quizzes, and AI-generated explanations — all in one interactive interface.

The project combines modern full-stack frontend engineering with AI-assisted reasoning workflows, making it relevant for education, research, technical training, and knowledge-intensive industries. Its architecture demonstrates production-aware React development, typed data modeling, Google Gemini integration, graph algorithms, and interactive 3D visualization.

Built with a zero-backend architecture and deployed serverlessly on Vercel, NeoGraph.AI shows how modern GenAI applications can be production-ready with just a frontend stack and a powerful LLM API.

---

✨ Key Features

• 🌐 Interactive 3D Knowledge Graph — Renders entities, semantic links, node labels, camera focus, and zoom controls using react-force-graph-3d, Three.js, and three-spritetext
• 🤖 AI-Powered Topic Expansion — Uses Google Gemini gemini-2.0-flash to generate 6–8 structured subtopics per selected graph node on demand
• 📄 Document-to-Graph Ingestion — Extracts 20 entities and 25 relationships from uploaded document topics using Gemini structured JSON output
• 🔗 Semantic Path Finding — Breadth-first search across graph links identifies and highlights the shortest relationship chain between any two concepts in 3D
• ⚙️ Real-Time Simulation Controls — D3 force parameters (stress, connectivity, energy, drift, entropy, stability) exposed through React state for live graph tuning
• 🧑‍🏫 AI Learning Assistant — Gemini 3 Pro preview with Google Search grounding generates deep reports, authoritative links, quizzes, and flashcards per node
• 🎨 Animated Responsive Dashboard — Built with React 19, TypeScript, Framer Motion, Lucide icons, and localStorage-backed session persistence
• 🗂 Category Clustering System — Collapses graph categories into hub nodes for cleaner exploration of large, dense knowledge networks

---

🛠 Tech Stack

Layer	Technology	Version
Frontend Framework	React + React DOM	19.2.3
Language	TypeScript	~5.8.2
Build Tool	Vite	^6.2.0
AI / LLM	@google/genai + @google/generative-ai	^1.38.0 / ^0.24.1
Gemini Models	gemini-2.0-flash, gemini-3-flash-preview, gemini-3-pro-preview	—
Search Grounding	Google Search (via Gemini tool config)	—
3D Graph Engine	react-force-graph-3d	^1.29.0
3D Rendering	Three.js	^0.182.0
3D Node Labels	three-spritetext	^1.10.0
Animations	Framer Motion	^12.29.0
Icons	Lucide React	^0.563.0
PDF Parsing	pdfjs-dist	^5.4.530
Session Storage	Browser localStorage	—
Deployment	Vercel (Serverless)	—
Styling	Tailwind CSS	—

---

🏗 System Architecture

Architecture Overview

User Browser
│
▼
React 19 + TypeScript SPA (Vite)
│
├──▶ Landing Page / Login / Dashboard
│        │
│        ▼
│   localStorage
│        │
│        └──▶ Persists lightweight user session
│
├──▶ Upload Panel
│        │
│        ▼
│   Google Gemini (gemini-3-flash-preview)
│        │
│        └──▶ Extracts graph nodes + links as typed JSON
│
├──▶ Knowledge Graph Engine
│        │
│        ├──▶ react-force-graph-3d
│        ├──▶ Three.js node + label rendering
│        └──▶ D3 force simulation parameter controls
│
├──▶ Knowledge Panel
│        │
│        ├──▶ Gemini 3 Pro Preview insight generation
│        ├──▶ Google Search grounding
│        └──▶ Quiz + flashcard generation
│
├──▶ Pathway Panel
│        │
│        ├──▶ BFS over graph adjacency structure
│        └──▶ Highlighted semantic path in 3D graph
│
▼
Vercel CDN
(Serverless Deployment • Zero Backend)
---

## 🚀 Getting Started

### Prerequisites

Make sure you have the following installed:

- [Node.js](https://nodejs.org/) v18 or higher
- npm v9 or higher
- A [Google Gemini API Key](https://aistudio.google.com/app/apikey) (free tier available)
- Git
- A modern browser with WebGL support for 3D graph rendering

### Installation

**1. Clone the repository**
```bash
git clone https://github.com/jayasri-88/genz.git
cd genz

2. Install dependencies

npm install

3. Set up environment variables

Create a .env.local file in the root directory:

cp .env.example .env.local

Add your Gemini API key to .env.local:

GEMINI_API_KEY=your_google_gemini_api_key
VITE_GEMINI_API_KEY=your_google_gemini_api_key

GEMINI_API_KEY is mapped through vite.config.ts. VITE_GEMINI_API_KEY is used directly by utils/ai.ts for client-side Gemini SDK access.

4. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

Production Build

# Build for production
npm run build

# Preview production build locally
npm run preview

---

📁 Project Structure

Project Structure

genz/
├── components/                         # React feature modules and UI components
│   ├── Auth/
│   │   └── Login.tsx                   # Login interface with local session initialization
│   │
│   ├── Graph/
│   │   └── KnowledgeGraph.tsx          # 3D graph renderer using react-force-graph-3d + Three.js
│   │
│   ├── Landing/
│   │   └── LandingPage.tsx             # Product landing page with CTA
│   │
│   ├── Layout/
│   │   ├── Sidebar.tsx                 # Primary dashboard navigation
│   │   └── Topbar.tsx                  # Top nav bar and user controls
│   │
│   ├── Panels/
│   │   ├── CategoryManager.tsx         # Category collapse and cluster management UI
│   │   ├── KnowledgePanel.tsx          # AI node reports, resources, quizzes, flashcards
│   │   ├── PathwayPanel.tsx            # BFS semantic path search between graph nodes
│   │   ├── ProfilePanel.tsx            # User profile and graph statistics
│   │   ├── SimulationPanel.tsx         # Graph force simulation parameter controls
│   │   ├── UploadPanel.tsx             # File upload flow and Gemini graph extraction
│   │   └── WorkflowPanel.tsx           # Focus workflow for selected graph nodes
│   │
│   └── Visuals/
│       └── BackgroundParticles.tsx     # Animated dashboard particle background
│
├── utils/
│   └── ai.ts                           # Gemini SDK helper for AI node/subtopic generation
│
├── App.tsx                             # Root component: routing, session logic, global state
├── index.tsx                           # React DOM bootstrap entry point
├── index.html                          # Vite HTML shell
├── metadata.json                       # Application metadata and configuration
├── types.ts                            # Global TypeScript interfaces and shared types
├── vite-env.d.ts                       # Vite environment typings
├── vite.config.ts                      # Vite config: plugins, aliases, env mapping
├── tsconfig.json                       # TypeScript compiler configuration
├── package.json                        # Dependency manifest and npm scripts
└── package-lock.json                   # Locked dependency tree

---

📡 API Documentation

NeoGraph.AI does not expose a custom REST API server. It is a client-side SPA that communicates directly with Google Gemini APIs through the official SDK.

Method	Model Used	Description	Input	Response
SDK Call	gemini-2.0-flash	Generates 6–8 subtopics for a selected graph node	Node name, category, description + JSON schema	{ subTopics: [{ name, category, description }] }
SDK Call	gemini-3-flash-preview	Extracts a full knowledge graph from an uploaded document topic	File-derived topic prompt + graph schema	{ nodes: [...], links: [...] }
SDK Call	gemini-3-pro-preview + Google Search grounding	Generates deep node intelligence, primary resources, quizzes, flashcards	Node name, category, structured schema + search tool config	{ summary, primaryResource, quiz, flashcards }

---

🧠 Model / Algorithm Details

NeoGraph.AI uses Google Gemini foundation models for structured generation, reasoning, summarization, quiz/flashcard generation, and web-grounded concept enrichment — no custom ML model is trained locally.

Graph Extraction Workflow Gemini is prompted to produce a typed JSON graph containing 20 nodes and 25 links. The app validates every generated link by confirming both its source and target exist in the node set before rendering, preventing malformed graph states at runtime.

Topic Expansion Workflow gemini-2.0-flash generates 6–8 related sub-concepts for any existing node. Generated nodes are assigned IDs, categories, colors, sizes, and spatial offsets, then merged into the live graph without a page reload.

Semantic Path Finding (BFS) The pathway module runs breadth-first search over the graph adjacency structure from an origin node to a target node. It tracks visited nodes to prevent cycles, returns the shortest discovered path, and highlights the full node-link chain directly inside the 3D visualization.

Simulation Parameter Formulas The force-directed graph exposes live controls. Two derived metrics are computed as:

• Entropy = (stress × 1.5 + energy × 0.8) / 2.3
• Stability = max(0, 100 − (drift × 2 + stress × 0.5))

No dataset splits, training loss curves, accuracy scores, or F1 benchmarks are included — the repository relies entirely on hosted foundation model inference.

---

📸 Screenshots / Demo

NeoGraph.AI landing page

3D interactive knowledge graph with category clustering

AI-generated node reports, quizzes, and flashcards

BFS-based semantic path highlighted in 3D

📺 View Live Demo →

---

💡 Use Cases

• Medical & Life Sciences Students — Convert dense textbooks or paper topics into interactive concept maps for faster systems-level understanding
• Researchers — Explore relationships between genes, proteins, diseases, mechanisms, and scientific concepts through graph-based discovery
• Legal, Policy & Government Analysts — Model complex knowledge domains as linked entities instead of isolated document notes
• Technical Educators — Generate quizzes, flashcards, and explainable concept summaries from any graph node to support active learning
• Product & Research Teams — Prototype AI-assisted knowledge exploration workflows for document-heavy domains

---

🗺 Roadmap

• Interactive 3D graph visualization with category clustering and semantic path highlighting
• Gemini-powered node expansion, graph extraction, quiz generation, and flashcard generation
• Persistent session management with localStorage and animated dashboard UI
• Deployed on Vercel with environment-based API key management (zero-backend)
• Add persistent cloud storage for users, uploaded documents, generated graphs, and learning history
• Implement authenticated backend APIs with role-based access control and secure API key proxying
• Add PDF text extraction using pdfjs-dist so uploaded documents are analyzed by content, not filename
• Add node click-to-expand for drill-down into sub-topic graphs
• Export knowledge graph as PNG / shareable JSON or URL
• Add automated testing, CI workflow, graph validation metrics, and performance benchmarks for large graphs

---

🤝 Contributing

Contributions are welcome from developers, designers, AI engineers, and technical writers!

1. Fork the repository

# Click "Fork" on GitHub, then clone your fork
git clone https://github.com/your-username/genz.git
cd genz

2. Create a feature branch

git checkout -b feature/your-feature-name

3. Install dependencies and run locally

npm install
npm run dev

4. Commit your changes

git add .
git commit -m "Add: your feature description"

5. Push and open a Pull Request

git push origin feature/your-feature-name

Open a Pull Request on GitHub describing: the problem solved, implementation details, screenshots, and testing performed.

---

📜 License

Distributed under the MIT License.

MIT License

Copyright (c) 2026 Jayasri

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

👩‍💻 Author

Jayasri

---

🙏 Acknowledgements

• Google Gemini APIs — Structured generation, concept reasoning, quiz/flashcard generation, and web-grounded answers
• React, TypeScript, and Vite — Modern frontend development tooling
• Three.js + react-force-graph-3d + three-spritetext — WebGL-based 3D graph visualization
• Framer Motion — Polished UI transitions and dashboard animations
• Lucide React — Icon system across navigation, panels, controls, and learning workflows
• PDF.js — In-browser PDF parsing by Mozilla
• Vercel — Serverless deployment and CDN hosting

---

If NeoGraph.AI helped you learn faster, give it a ⭐ — it means a lot!

🚀 Try it live →