DevGraph

AI-powered repository intelligence — ask questions about any codebase in plain English.

DevGraph transforms a GitHub repository into a persistent knowledge graph, then lets you explore it through a natural language chat interface and an interactive visual graph. Instead of scanning files every time you ask a question, DevGraph stores the entire architecture of a codebase — files, classes, functions, imports, and their relationships — permanently in Neo4j, enabling fast, accurate, graph-grounded AI answers.

---

What it does

Paste any public GitHub URL. DevGraph will:

1. Clone the repository locally
2. Parse every source file using tree-sitter to extract functions, classes, and imports
3. Build a persistent knowledge graph in Neo4j representing the full architecture
4. Answer natural language questions by combining graph retrieval with Gemini AI

Ask things like:

• "How does routing work in this codebase?"
• "What does the Flask class depend on?"
• "Which files handle authentication?"
• "What will break if I modify the Request class?"

Click any node in the graph panel and DevGraph automatically asks about it in the chat — the graph is a navigation interface, not just a decoration.

---

Screenshots

Chat panel answering "What does the Flask class depend on?" with a full breakdown of standard library, third-party, and internal dependencies — sourced entirely from the knowledge graph.

---

Tech stack

Layer	Technology
Backend API	Python, FastAPI, Uvicorn
Source parsing	tree-sitter, tree-sitter-python
Knowledge graph	Neo4j, Cypher
AI reasoning	Google Gemini 2.5 Flash
Graph retrieval	Custom graph-RAG pipeline
Frontend	React, Vite
Graph visualisation	Cytoscape.js, cose-bilkent layout
HTTP client	Axios

---

Architecture

GitHub URL
    ↓
Repo Cloner (GitPython)
    ↓
AST Parser (tree-sitter)
    ↓                          
Knowledge Graph (Neo4j)  ←──── persistent, queryable
    ↓
Graph Retriever  ←──── intent-aware Cypher queries
    ↓
Gemini 2.5 Flash  ←──── grounded AI reasoning
    ↓
React Frontend  ←──── chat + interactive graph

The AI never scans raw files — it only reasons over structured graph data. This makes answers faster, cheaper, and grounded in real structural relationships rather than text similarity.

---

Project structure

devgraph/
├── backend/
│   ├── main.py                  # FastAPI app + all endpoints
│   ├── services/
│   │   └── repo_cloner.py       # GitHub repo cloning
│   ├── parsers/
│   │   └── python_parser.py     # tree-sitter AST extraction
│   ├── graph/
│   │   ├── graph_service.py     # Neo4j queries + write operations
│   │   └── graph_builder.py     # Parse → graph pipeline
│   └── ai/
│       ├── query_analyzer.py    # Intent classification
│       ├── graph_retriever.py   # Context retrieval from Neo4j
│       └── ai_answerer.py       # Gemini prompt + response
├── frontend/
│   └── src/
│       ├── App.jsx              # Root layout + state
│       ├── components/
│       │   ├── ChatPanel.jsx    # Chat interface
│       │   └── GraphView.jsx    # Cytoscape graph
│       └── api/
│           └── devgraphApi.js   # API client
├── .env.example
├── requirements.txt
└── README.md

---

API endpoints

Method	Endpoint	Description
POST	/repo/clone	Clone a GitHub repository
POST	/repo/build-graph	Parse repo and build knowledge graph
POST	/repo/{name}/ask	Ask a natural language question
GET	/repo/{name}/structure	Get file/class/function structure
GET	/repo/{name}/dependencies	Get most imported modules
GET	/repo/{name}/graph-data	Get nodes + links for visualisation
GET	/function/{name}	Find a function across all repos

---

Setup

Prerequisites

• Python 3.10+
• Node.js 18+
• Git
• Neo4j Desktop with a local instance running on bolt://localhost:7687
• A Google Gemini API key (free tier)

1. Clone this repo

git clone https://github.com/Raj-cyber9/devgraph.git
cd devgraph

2. Backend setup

# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux

# Install dependencies
pip install -r requirements.txt

3. Environment variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password
GEMINI_API_KEY=your_gemini_api_key

4. Frontend setup

cd frontend
npm install

---

Running the project

You need three things running simultaneously:

1. Neo4j — open Neo4j Desktop and start your local instance (green dot)

2. Backend — in terminal from devgraph/:

venv\Scripts\activate
uvicorn backend.main:app --reload

3. Frontend — in a second terminal from devgraph/frontend/:

npm run dev

Then open http://localhost:5173

---

Usage

1. Paste a public GitHub URL (e.g. https://github.com/pallets/flask)
2. Click Run — DevGraph clones the repo and builds the knowledge graph (30–90 seconds for the first run)
3. Ask questions in the chat panel
4. Click any node in the graph to instantly ask about it

The graph build is persistent — subsequent runs on the same repo are instant since the data is already in Neo4j.

---

How the AI reasoning works

DevGraph uses a custom graph-RAG (Retrieval Augmented Generation) pipeline:

1. Intent classification — the question is analyzed to determine what kind of information is needed (concept explanation, file location, dependency mapping, impact analysis, etc.)
2. Graph retrieval — targeted Cypher queries fetch relevant nodes from Neo4j based on the detected intent and extracted keywords
3. Context building — retrieved graph data is formatted into structured context
4. AI generation — Gemini receives the context plus the original question and generates a grounded answer

The AI only sees real, extracted graph data — it cannot hallucinate file names, function names, or relationships that don't exist in the codebase.

---

Current limitations

• Python repositories only (JavaScript/TypeScript/Go/Rust planned)
• Static analysis only — dynamic imports and runtime behavior are not captured
• Decorator-based route registration (@app.route) not yet stored as structured graph data
• Large repositories (10,000+ files) may require increased Neo4j memory allocation

---

Roadmap

• Multi-language support (JavaScript, TypeScript, Go, Rust)
• Multiple repo sidebar with quick switching
• Repo health dashboard (complexity hotspots, dead code, circular dependencies)
• Highlight graph nodes mentioned in AI answers
• GitHub webhook integration for automatic re-indexing on push
• VS Code extension
• Self-hosted Docker Compose deployment

---

Contributing

Pull requests are welcome. For major changes, open an issue first to discuss what you'd like to change.

---