CodeGraph

Visualize any codebase as an interactive knowledge graph.

Upload a codebase and explore it at multiple levels — folders, files, classes, functions — seeing how every node connects to the others, what it takes as input, and what it produces as output. Think of it as a persistent, zoomable version of your IDE's call-stack view.

---

Features

Feature	Description
Multi-level views	Switch between Folder → File → Class → Function granularity
Call graph	See which functions call which, with arrows
Import graph	See how files/modules depend on each other
Inheritance graph	Visualize class hierarchies
Node detail panel	Parameters, return types, docstrings, callers, callees
AI analysis	One-click Claude-powered description of any node
Natural language Q&A	Ask "Which functions handle authentication?"
Search	Instant highlight of matching nodes
3 input modes	Upload .zip · Clone git URL · Point to local directory
Languages	Python (full AST) · JavaScript/TypeScript (regex + tree-sitter)

---

Quick Start

Option A — Local development (recommended for private code)

cd codegraph

# Optional: set your API key to enable AI features
export ANTHROPIC_API_KEY=sk-ant-...

./start_local.sh
# Open http://localhost:5173

Option B — Docker (single container, production-ready)

cd codegraph

# Build and run
docker-compose up --build

# Open http://localhost:8000

Option C — Manual

# Backend
cd codegraph
pip install -r backend/requirements.txt
uvicorn backend.main:app --host 0.0.0.0 --port 8000

# Frontend (separate terminal)
cd codegraph/frontend
npm install
npm run dev
# Open http://localhost:5173

---

Architecture

codegraph/
├── backend/
│   ├── main.py              # FastAPI app (REST API + static file serving)
│   ├── graph_builder.py     # Orchestrates parsers → Graph
│   ├── models.py            # Graph, GraphNode, GraphEdge, NodeType, EdgeType
│   ├── ai_enricher.py       # Claude API integration (node descriptions, Q&A)
│   ├── parsers/
│   │   ├── python_parser.py # Python: uses built-in `ast` module
│   │   └── js_parser.py     # JS/TS: tree-sitter (with regex fallback)
│   └── requirements.txt
│
├── frontend/
│   └── src/
│       ├── App.tsx                     # Root layout and state routing
│       ├── hooks/useGraph.ts           # All API communication + state
│       ├── types.ts                    # TypeScript types
│       └── components/
│           ├── GraphViewer.tsx         # Cytoscape.js canvas
│           ├── NodePanel.tsx           # Selected node details
│           ├── LevelSelector.tsx       # Level switch + stats
│           ├── UploadPanel.tsx         # Upload/Git/Local input
│           └── Toolbar.tsx             # Search + AI Q&A
│
├── Dockerfile                          # Multi-stage: node build + python serve
├── docker-compose.yml
├── start_local.sh                      # Development startup script
└── README.md

---

API Reference

Method	Endpoint	Description
POST	/api/upload	Upload a .zip of a codebase
POST	/api/analyze-git	Clone and analyze a git repo
POST	/api/analyze-local	Analyze a local directory
GET	/api/graph/{level}	Graph in Cytoscape.js format (folder/file/class/function)
GET	/api/node/{id}	Full details for a single node
POST	/api/ai/describe/{id}	AI description of a node
POST	/api/ai/ask	Natural language Q&A
GET	/api/search?q=	Search nodes by name
GET	/api/stats	Graph statistics

---

Adding Tree-sitter for Better JS/TS Parsing

By default, JS/TS files are parsed with regex (fast, no extra deps). For more accurate parsing:

pip install tree-sitter tree-sitter-javascript tree-sitter-typescript

The parser will automatically use tree-sitter when available.

---

Extending to More Languages

1. Create backend/parsers/your_lang_parser.py implementing a class with parse_into(graph: Graph).
2. Import and call it in backend/graph_builder.py.

The Graph, GraphNode, GraphEdge, NodeType, and EdgeType models in models.py are language-agnostic.

---

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	Required for AI features (node descriptions, Q&A)
CODEGRAPH_PROJECTS_DIR	Directory to mount in Docker for local analysis