🗺️ Branchdeck

Understand large codebases in hours, not weeks.

Branchdeck is a developer intelligence platform that parses your codebase with tree-sitter, builds a live dependency graph backed by PostgreSQL + pgvector, and surfaces four AI-powered features — Project Map, Visual Call Flow, Impact Analysis, and Story Mode — all from a Next.js web app and a VS Code extension.

✨ Features

Feature	Description	Status
🗺️ AI Project Map	Generates a dependency graph of your entire codebase, colour-coded by layer (UI, API, DB, worker, external, service)	✅ Live
🔀 Visual Call Flow	Renders an interactive node graph of function call chains up to 3 hops deep, sourced from real AST data	✅ Live
💥 Impact Analysis	Runs a CTE query on the graph to find every downstream node that would be affected by changing a symbol	✅ Live
📖 Story Mode	AI-generated narrative walkthrough of architecture paths, powered by Gemini (with a local rules narrator fallback)	✅ Live
💬 Codebase Q&A	Natural-language queries against the dependency graph	🟡 Demo

⚙️ Architecture

┌─────────────────────────────────────────────────────────┐
│                      User Browser                       │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│           Next.js Frontend (Port 3000)                  │
│   page.tsx · /api/analyze · /api/callflow               │
│            /api/impact · /api/story                     │
│                                                         │
│  Fallback: ts-morph local AST parser (offline mode)     │
└──────────────────────────┬──────────────────────────────┘
                           │  JWT-authenticated proxy
┌──────────────────────────▼──────────────────────────────┐
│           FastAPI Engine (Port 8000)                    │
│   /api/analyze · /api/impact · /api/callflow            │
│   /api/story · Pydantic validation · JWT verification   │
│                                                         │
│   tree-sitter parser.py  ·  database.py ORM            │
│   Gemini API (optional)  ·  JSON structured logging     │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│     PostgreSQL + pgvector (Port 5432)                   │
│  repos · commits · code_nodes · code_edges · file_cache │
└─────────────────────────────────────────────────────────┘

Request flow at a glance

/api/analyze — Proxies to FastAPI → tree-sitter parses files → graph written to Postgres. Falls back to ts-morph if FastAPI is offline.
/api/callflow — Queries code_nodes / code_edges with a BFS up to depth 3.
/api/impact — Executes a recursive CTE (get_downstream_impact) on the graph.
/api/story — Traces graph paths → Gemini API narrative (or local rules narrator if GEMINI_API_KEY is absent).

📁 Project Structure

Branchdeck/
├── backend/                  # FastAPI engine
│   ├── main.py               # All API routes, BFS, CTE queries, story generation
│   ├── parser.py             # tree-sitter AST → code_nodes / code_edges
│   ├── database.py           # SQLAlchemy ORM, schema, pgvector setup
│   ├── secure_file_handler.py
│   ├── services/
│   ├── test_api.py           # Integration + security tests (testcontainers)
│   ├── test_parser.py
│   ├── requirements.txt
│   └── Dockerfile
│
├── webapp/                   # Next.js frontend
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx      # Main dashboard (66 KB — all four features)
│   │   │   ├── api/          # Next.js route handlers (proxy + fallback)
│   │   │   └── layout.tsx
│   │   ├── components/       # React component library
│   │   └── lib/
│   │       └── server-analyzer.ts  # ts-morph fallback AST parser
│   ├── package.json
│   └── Dockerfile
│
├── extension/                # VS Code extension
│   ├── src/                  # Extension source
│   ├── media/                # Icons
│   ├── package.json          # Commands, menus, activation events
│   └── branchdeck-vscode-*.vsix
│
├── landing/                  # Static marketing site
│   ├── index.html
│   ├── style.css
│   └── app.js
│
├── docker-compose.yml        # Full-stack: db + backend + webapp
├── ARCHITECTURE_AS_BUILT.md  # Detailed verified architecture notes
└── RUNBOOK.md                # Step-by-step setup guide

📋 Prerequisites

Requirement	Version	Notes
Node.js	≥ 18	For the Next.js webapp
Python	≥ 3.12	For the FastAPI backend
PostgreSQL	≥ 16 with pgvector	Or use Docker Compose
Docker & Docker Compose	Any recent	Optional — for one-command full-stack startup
Git	Any	Required for repo analysis

🛠️ Local Development

1. Database

Start a local Postgres + pgvector instance (the quickest way):

docker compose up db -d

Or point DATABASE_URL to any existing PostgreSQL 16+ server with pgvector enabled.

2. Backend (FastAPI)

cd backend

# Create and activate a virtual environment
python -m venv venv

# Windows (PowerShell)
.\\venv\\Scripts\\Activate.ps1
# macOS / Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment (see Environment Variables below)
# Start the server with live reload
uvicorn main:app --reload --port 8000

Interactive API docs are available at http://localhost:8000/docs.

3. Frontend (Next.js)

In a new terminal:

cd webapp
npm install
npm run dev

Open http://localhost:3000 in your browser. The Next.js API routes automatically proxy backend requests to FastAPI on port 8000.

Offline mode: If the FastAPI backend is unreachable, the frontend transparently falls back to local TypeScript AST parsing using ts-morph. You'll still get a working project map — without database persistence.

🐳 Docker (Full Stack)

Spin up the entire stack — database, backend, and webapp — with a single command:

# Copy and fill in your secrets first
cp .env.example .env   # or set the variables below manually

docker compose up --build

Services:

Service	Port	URL
webapp (Next.js)	3000	http://localhost:3000
backend (FastAPI)	8000	http://localhost:8000/docs
db (PostgreSQL + pgvector)	5432	localhost:5432

🔑 Environment Variables

Backend (`backend/`)

Variable	Description	Default
`DATABASE_URL`	PostgreSQL connection string	`postgresql://postgres:postgres@localhost:5432/postgres`
`GEMINI_API_KEY`	Enables AI-generated Story Mode narratives	Optional — falls back to local rule narrator
`SUPABASE_JWT_SECRET`	Secret used to verify JWT tokens from Next.js	`dev_jwt_secret_change_me_in_prod_32chars`
`ALLOWED_ORIGINS`	CORS allowed origins (comma-separated)	`http://localhost:3000`
`GITHUB_TOKEN`	GitHub API token for private repository access	Optional

⚠️ Fail-fast: The backend will refuse to start if DATABASE_URL contains postgresql:// but the server is unreachable. Silent SQLite fallback is intentionally disabled to prevent environment drift.

Webapp (`webapp/`)

Variable	Description
`BACKEND_URL`	Internal URL of the FastAPI backend (used by Next.js server-side proxy)
`NEXT_PUBLIC_SUPABASE_URL`	Supabase project URL (for future auth integration)
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Supabase anon key
`SUPABASE_JWT_SECRET`	Must match the backend secret

🧪 Running Tests

Backend (Python)

Runs the full integration and security test suite against a real PostgreSQL container:

cd backend
pytest

Requires Docker to be running — tests use testcontainers-postgres to spin up an isolated database automatically. No silent SQLite fallback.

The security test suite (test_api.py) explicitly verifies:

Expired JWT tokens are rejected
alg: none exploit attempts are blocked
Incorrect signature algorithms are rejected
Cross-tenant queries return 403 Forbidden

Frontend (TypeScript)

Type-check the entire webapp without emitting:

cd webapp
npx tsc --noEmit

🧩 VS Code Extension

Branchdeck ships a VS Code extension that embeds all four features directly in your editor.

Install from `.vsix`

code --install-extension extension/branchdeck-vscode-0.1.5.vsix

Or install via the VS Code Extensions panel → Install from VSIX… → select extension/branchdeck-vscode-0.1.5.vsix.

Commands

Command	How to trigger	Description
`Branchdeck: Show AI Project Map`	Command Palette	Renders the full codebase dependency graph
`Branchdeck: Visual Call Flow (Selected Function)`	Right-click any selection	Shows the call chain from the selected function
`Branchdeck: Analyze Impact Scope`	Right-click any selection	Shows all code affected if this symbol changes
`Branchdeck: Architecture Walkthrough`	Command Palette	Generates an AI Story Mode walkthrough

📖 API Reference

All endpoints are on the FastAPI backend (port 8000). Next.js /api/* routes proxy to these with JWT-authenticated headers.

`POST /api/analyze`

Clones or scans a repository, parses all files with tree-sitter, and persists the dependency graph.

Request body:

{
  "repoUrl": "https://github.com/owner/repo",
  "branch": "main"
}

`GET /api/callflow`

Returns a call graph for a specific function up to 3 hops deep.

Query params: nodeId, commitSha

`POST /api/impact`

Returns all downstream nodes impacted by a change to a specific symbol.

Request body:

{
  "targetNodeId": "repo_id:sha:file_path",
  "commitSha": "abc123",
  "symbolName": "processPayment"
}

`GET /api/story`

Generates an AI narrative walkthrough for traced graph paths. Uses Gemini API if configured; runs a local rule-based narrator otherwise.

Query params: commitSha, repoId

Full interactive documentation: http://localhost:8000/docs

🔒 Security

JWT verification is enabled on all FastAPI endpoints. Every request must carry a Authorization: Bearer <token> header signed with SUPABASE_JWT_SECRET.
Tenant isolation: All queries filter by the verified owner from the JWT claim. Cross-tenant access raises 403 Forbidden.
Pydantic validation enforces the API contract on every inbound payload.
Structured correlation IDs (X-Correlation-ID) propagate from Next.js proxy to FastAPI for end-to-end request tracing.

⚠️ Dev placeholder: The 'local' org claim in the current Next.js proxy is a development placeholder. Full multi-tenant isolation requires integrating a real auth provider (Supabase Auth or Clerk) on the frontend.

🤝 Contributing

Contributions are welcome! Areas of particular interest:

Real auth provider integration — wiring Supabase Auth or Clerk to replace the 'local' dev placeholder
Codebase Q&A — replacing the client-side regex simulation with a real pgvector semantic search
Additional language support — extending the tree-sitter parser beyond TypeScript/JavaScript
Viem/ethers signer — production wallet integration for any payment features
Performance — async graph indexing (current implementation is synchronous, blocking the request)

Development workflow

git clone https://github.com/dragon486/Branchdeck.git
cd Branchdeck

# Start the database
docker compose up db -d

# Backend
cd backend && python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Frontend (new terminal)
cd webapp && npm install && npm run dev

# Tests
cd backend && pytest
cd webapp && npx tsc --noEmit

See RUNBOOK.md for the full operations guide and ARCHITECTURE_AS_BUILT.md for a verified deep-dive into the system design.

📄 License

Built to make large codebases human-scale.

GitHub · Issues · VS Code Extension

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
backend		backend
doc/adr		doc/adr
extension		extension
reports		reports
scripts		scripts
webapp		webapp
.gitignore		.gitignore
ARCHITECTURE_AS_BUILT.md		ARCHITECTURE_AS_BUILT.md
README.md		README.md
RUNBOOK.md		RUNBOOK.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
test_branchdeck.db		test_branchdeck.db

Navigation Menu

Uh oh!

Repository files navigation

🗺️ Branchdeck

Table of Contents

✨ Features

⚙️ Architecture

Request flow at a glance

📁 Project Structure

📋 Prerequisites

🛠️ Local Development

1. Database

2. Backend (FastAPI)

3. Frontend (Next.js)

🐳 Docker (Full Stack)

🔑 Environment Variables

Backend (`backend/`)

Webapp (`webapp/`)

🧪 Running Tests

Backend (Python)

Frontend (TypeScript)

🧩 VS Code Extension

Install from `.vsix`

Commands

📖 API Reference

`POST /api/analyze`

`GET /api/callflow`

`POST /api/impact`

`GET /api/story`

🔒 Security

🤝 Contributing

Development workflow

📄 License

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

🗺️ Branchdeck

Table of Contents

✨ Features

⚙️ Architecture

Request flow at a glance

📁 Project Structure

📋 Prerequisites

🛠️ Local Development

1. Database

2. Backend (FastAPI)

3. Frontend (Next.js)

🐳 Docker (Full Stack)

🔑 Environment Variables

Backend (backend/)

Webapp (webapp/)

🧪 Running Tests

Backend (Python)

Frontend (TypeScript)

🧩 VS Code Extension

Install from .vsix

Commands

📖 API Reference

POST /api/analyze

GET /api/callflow

POST /api/impact

GET /api/story

🔒 Security

🤝 Contributing

Development workflow

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Backend (`backend/`)

Webapp (`webapp/`)

Install from `.vsix`

`POST /api/analyze`

`GET /api/callflow`

`POST /api/impact`

`GET /api/story`