Architecture

How RepoPilot indexes repositories, stores graph data, and serves intelligence features.

High-level flow

GitHub URL / local path
       ↓
  clone or read files
       ↓
  syncRepository (Tree-sitter parse)
       ↓
  buildDependencyGraph
       ↓
  indexRepositorySearch (chunks + embeddings)
       ↓
  ingestRepositoryHistory (git log)
       ↓
  Dashboard + REST API + MCP tools

Technology stack

Layer	Technology	Role
Web UI	Next.js (Pages Router), React, Motion	Dashboard, BFF auth routes, public shell
API	Fastify, Zod	REST endpoints, webhooks, rate limiting
Database	PostgreSQL + pgvector, Prisma 7	Files, symbols, graphs, code chunks, vectors
Queue	Redis + QueuedJob table	Background repo-sync jobs
Parsing	tree-sitter (JS/TS)	AST symbols, imports, exports
Search	tsvector + pgvector	Lexical + semantic hybrid search
Graph viz	Mermaid, dagre, elkjs, react-force-graph-2d	Architecture views
AI	Groq / Gemini / Ollama (pluggable)	Ask + optional embeddings
Agents	MCP SDK (stdio)	Cursor / Claude Desktop integration

Indexing pipeline

1. Repository sync

Walks source files, parses with Tree-sitter, and persists File, Symbol, FileImport, and FileExport rows per revision. Concurrency is controlled by SYNC_CONCURRENCY.

2. Dependency graph

Resolves import paths to module edges and symbol cross-references. Stores ModuleDependency and SymbolDependency. Powers Architecture, Impact, and graph boosts in search ranking.

3. Search index

Splits file content into overlapping line chunks (~40 lines, 8-line overlap). Embeddings are stored as pgvector columns; searchVector is a generated tsvector for full-text search. Inserts use batched raw SQL inside a Prisma interactive transaction (vector type is Unsupported in Prisma schema).

4. History ingest

Reads recent commits (capped by HISTORY_MAX_COMMITS) to populate CommitRecord, CoChangePair, and ModuleHotspot.

Design decisions

Deterministic graphs over LLM sketches — dependency edges come from parsed imports, not generated diagrams. Safer for refactors and impact analysis.
Revision-scoped data — every indexed artifact ties to a RepositoryRevision SHA so views can pin to a commit.
BFF auth in Next.js — GitHub OAuth and session cookies live in the web app; API calls use INTERNAL_API_SECRET from server routes.
Queue + inline indexing — production uses a worker; local dev sets INDEX_INLINE=true to skip Redis worker setup.
Pluggable LLM/embeddings — Ask works with Groq/Gemini free tiers; search falls back to local-hash embeddings when no API key is set.
Monorepo with Turbo — shared GitHub helpers in common; single yarn dev for parallel API + web.

Repository identity

Public repositories get a stable UUID derived from the GitHub owner/repo slug via deriveRepositoryId in @repopilot/common. Dashboard URLs use this ID:

/dashboard/e66b9dbb-8c37-4622-87c5-4fbf0132fe6c