How benitamags/codebrief works
Purpose and Entry Points
Codebrief is a full-stack repository-analysis product: users submit repositories, backend workers derive architectural knowledge, and a Next.js UI presents summaries, graphs, guided exploration, and reading order. Backend startup is backend/src/index.ts; frontend routes begin at frontend/app/page.tsx and repository-specific views under frontend/app/repo/[id]/.
HTTP API and Client Boundary
The backend exposes route groups for repository intake, chat, architecture graphs, guided explanations, reading plans, and server-sent events (SSE): backend/src/api/routes/repo.routes.ts, backend/src/api/routes/graph.routes.ts, backend/src/api/routes/sse.routes.ts. The frontend centralizes backend calls in frontend/app/lib/api.ts, separating UI route components from transport details.
Repository Analysis Pipeline
Repository analysis is asynchronous: enqueueing occurs in backend/src/queue/analyze.queue.ts, while execution is handled by backend/src/workers/analyze.worker.ts. This is the principal control boundary between request-time repository creation and expensive cloning/parsing/AI enrichment. Progress and live status are published through backend/src/services/progress.service.ts and backend/src/services/sse.service.ts.
AI Agent Orchestration
A multi-agent layer converts code-derived context into architectural output. backend/src/agents/orchestrator.ts coordinates specialized agents: cartography for structural mapping (backend/src/agents/cartographer.agent.ts), prioritization (backend/src/agents/prioritizer.agent.ts), summarization (backend/src/agents/summarizer.agent.ts), and interactive guidance (backend/src/agents/guide.agent.ts). Shared LLM and embedding access are abstracted in backend/src/lib/llm.ts and backend/src/lib/embeddings.ts.
Code Understanding and Retrieval
Static source analysis is rooted in AST processing at backend/src/lib/ast.ts. Repository content and derived chunks are made retrievable through RAG/vector services: backend/src/services/rag.service.ts and backend/src/services/vector.service.ts. This forms the evidence boundary for agent responses: agents should operate on extracted repository context rather than direct frontend input alone.
Persistence and External Systems
PostgreSQL is the relational system of record, with schema and migrations in backend/src/db/schema.ts and backend/src/db/migrations/. Neo4j stores or serves code relationships via backend/src/db/neo4j.ts and backend/src/services/neo4j.service.ts. GitHub acquisition is encapsulated by backend/src/services/github.service.ts; caching is isolated in backend/src/services/cache.service.ts. Environment validation/configuration lives in backend/src/config/env.ts.
Presentation Surfaces
Repository detail is organized into dedicated UI modes: overview at frontend/app/repo/[id]/page.tsx, architecture at frontend/app/repo/[id]/architecture/page.tsx, mind map at frontend/app/repo/[id]/mindmap/page.tsx, and reading order at frontend/app/repo/[id]/reading-order/page.tsx. Shared visualization components include frontend/app/components/code-canvas.tsx and frontend/app/components/code-snippets.tsx. Docker deployment is defined by docker-compose.yml and backend/Dockerfile.
Main entry points: orchestrator.ts Agent orchestrator · analyze.worker.ts Analysis worker · index.ts Backend server · repo.routes.ts Repository API
Components 24
Next.js Frontend
- Repository submission
frontend/app/page.tsx - Repository views · Overview, architecture, mind map, and reading order screens.
frontend/app/repo/[id]/page.tsx - Code visualizations
frontend/app/components/code-canvas.tsx - Backend API client
frontend/app/lib/api.ts
Backend API
- Backend server
backend/src/index.ts - Repository API · Accepts repository intake requests.
backend/src/api/routes/repo.routes.ts - Graph API · Serves architecture, chat, and reading-plan results.
backend/src/api/routes/graph.routes.ts - SSE API
backend/src/api/routes/sse.routes.ts
Analysis & AI Pipeline
- Analysis queue
backend/src/queue/analyze.queue.ts - Analysis worker · Clones, parses, indexes, and enriches submitted repositories.
backend/src/workers/analyze.worker.ts - AST analysis
backend/src/lib/ast.ts - Agent orchestrator
backend/src/agents/orchestrator.ts - Cartography agent
backend/src/agents/cartographer.agent.ts - Prioritization agent
backend/src/agents/prioritizer.agent.ts - Summarization agent
backend/src/agents/summarizer.agent.ts - Guidance agent
backend/src/agents/guide.agent.ts - RAG retrieval
backend/src/services/rag.service.ts - Progress publishing
backend/src/services/progress.service.ts - SSE publisher
backend/src/services/sse.service.ts - LLM & embeddings
backend/src/lib/llm.ts
Data & External Systems
- Vector store service
backend/src/services/vector.service.ts - PostgreSQL · Repository records and derived relational data.
backend/src/db/schema.ts - Neo4j code graph
backend/src/services/neo4j.service.ts - GitHub acquisition
backend/src/services/github.service.ts
Connections 28
- Repository submission → Backend API client: submits repository
- Repository views → Backend API client: loads analysis
- Repository views → Code visualizations: renders
- Backend API client → Backend server: HTTP / SSE
- Backend server → Repository API: mounts
- Backend server → Graph API: mounts
- Backend server → SSE API: mounts
- Repository API → Analysis queue: enqueues
- Repository API → PostgreSQL: creates repository
- Analysis queue → Analysis worker: dispatches job
- Analysis worker → GitHub acquisition: acquires source
- Analysis worker → AST analysis: parses source
- AST analysis → Neo4j code graph: writes relationships
- AST analysis → RAG retrieval: produces chunks
- RAG retrieval → Vector store service: indexes and retrieves
- Analysis worker → Agent orchestrator: enriches analysis
- Agent orchestrator → Cartography agent: delegates mapping
- Agent orchestrator → Prioritization agent: delegates ranking
- Agent orchestrator → Summarization agent: delegates summary
- Agent orchestrator → Guidance agent: delegates guidance
- Agent orchestrator → RAG retrieval: retrieves evidence
- Agent orchestrator → LLM & embeddings: uses AI access
- Agent orchestrator → PostgreSQL: persists outputs
- Analysis worker → Progress publishing: reports status
- Progress publishing → SSE publisher: publishes updates
- SSE publisher → SSE API: streams events
- Graph API → PostgreSQL: reads results
- Graph API → Neo4j code graph: reads code graph