# benitamags/codebrief architecture

> Architecture diagram of the GitHub repository benitamags/codebrief, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benitamags/codebrief
- Repository: https://github.com/benitamags/codebrief

## Overview

#### 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: [`backend/src/agents/orchestrator.ts`](https://github.com/benitamags/codebrief/blob/main/backend/src/agents/orchestrator.ts) (Agent orchestrator), [`backend/src/workers/analyze.worker.ts`](https://github.com/benitamags/codebrief/blob/main/backend/src/workers/analyze.worker.ts) (Analysis worker), [`backend/src/index.ts`](https://github.com/benitamags/codebrief/blob/main/backend/src/index.ts) (Backend server), [`backend/src/api/routes/repo.routes.ts`](https://github.com/benitamags/codebrief/blob/main/backend/src/api/routes/repo.routes.ts) (Repository API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Frontend"]
  node_home["Repository submission<br/>Next.js route<br/>[page.tsx]"]
  node_repo_views["Repository views<br/>Next.js routes<br/>[page.tsx]"]
  node_visualizations["Code visualizations<br/>React components<br/>[code-canvas.tsx]"]
  node_api_client["Backend API client<br/>transport boundary<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_backend_entry{{"Backend server<br/>application entry<br/>[index.ts]"}}
  node_repo_api["Repository API<br/>HTTP routes<br/>[repo.routes.ts]"]
  node_graph_api["Graph API<br/>HTTP routes<br/>[graph.routes.ts]"]
  node_sse_api["SSE API<br/>HTTP routes<br/>[sse.routes.ts]"]
end

subgraph group_pipeline["Analysis &amp; AI Pipeline"]
  node_analysis_queue["Analysis queue<br/>async job boundary<br/>[analyze.queue.ts]"]
  node_analysis_worker{{"Analysis worker<br/>background worker<br/>[analyze.worker.ts]"}}
  node_source_analysis["AST analysis<br/>code extraction<br/>[ast.ts]"]
  node_orchestrator{{"Agent orchestrator<br/>multi-agent coordinator<br/>[orchestrator.ts]"}}
  node_cartographer["Cartography agent<br/>structure mapping agent"]
  node_prioritizer["Prioritization agent<br/>analysis agent"]
  node_summarizer["Summarization agent<br/>analysis agent"]
  node_guide["Guidance agent<br/>interactive agent<br/>[guide.agent.ts]"]
  node_rag["RAG retrieval<br/>evidence service<br/>[rag.service.ts]"]
  node_progress["Progress publishing<br/>live status service"]
  node_sse_service["SSE publisher<br/>event delivery service<br/>[sse.service.ts]"]
  node_llm["LLM &amp; embeddings<br/>AI provider abstraction<br/>[llm.ts]"]
end

subgraph group_data["Data &amp; External Systems"]
  node_vector["Vector store service<br/>embedding retrieval<br/>[vector.service.ts]"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[schema.ts]")]
  node_neo4j[("Neo4j code graph<br/>relationship store<br/>[neo4j.service.ts]")]
  node_github["GitHub acquisition<br/>repository source<br/>[github.service.ts]"]
end

node_home -->|"submits repository"| node_api_client
node_repo_views -->|"loads analysis"| node_api_client
node_repo_views -->|"renders"| node_visualizations
node_api_client -->|"HTTP / SSE"| node_backend_entry
node_backend_entry -->|"mounts"| node_repo_api
node_backend_entry -->|"mounts"| node_graph_api
node_backend_entry -->|"mounts"| node_sse_api
node_repo_api -->|"enqueues"| node_analysis_queue
node_repo_api -->|"creates repository"| node_postgres
node_analysis_queue -->|"dispatches job"| node_analysis_worker
node_analysis_worker -->|"acquires source"| node_github
node_analysis_worker -->|"parses source"| node_source_analysis
node_source_analysis -->|"writes relationships"| node_neo4j
node_source_analysis -->|"produces chunks"| node_rag
node_rag -->|"indexes and retrieves"| node_vector
node_analysis_worker -->|"enriches analysis"| node_orchestrator
node_orchestrator -->|"delegates mapping"| node_cartographer
node_orchestrator -->|"delegates ranking"| node_prioritizer
node_orchestrator -->|"delegates summary"| node_summarizer
node_orchestrator -->|"delegates guidance"| node_guide
node_orchestrator -->|"retrieves evidence"| node_rag
node_orchestrator -->|"uses AI access"| node_llm
node_orchestrator -->|"persists outputs"| node_postgres
node_analysis_worker -->|"reports status"| node_progress
node_progress -->|"publishes updates"| node_sse_service
node_sse_service -->|"streams events"| node_sse_api
node_graph_api -->|"reads results"| node_postgres
node_graph_api -->|"reads code graph"| node_neo4j

click node_home "https://github.com/benitamags/codebrief/blob/main/frontend/app/page.tsx"
click node_repo_views "https://github.com/benitamags/codebrief/blob/main/frontend/app/repo/%5Bid%5D/page.tsx"
click node_visualizations "https://github.com/benitamags/codebrief/blob/main/frontend/app/components/code-canvas.tsx"
click node_api_client "https://github.com/benitamags/codebrief/blob/main/frontend/app/lib/api.ts"
click node_backend_entry "https://github.com/benitamags/codebrief/blob/main/backend/src/index.ts"
click node_repo_api "https://github.com/benitamags/codebrief/blob/main/backend/src/api/routes/repo.routes.ts"
click node_graph_api "https://github.com/benitamags/codebrief/blob/main/backend/src/api/routes/graph.routes.ts"
click node_sse_api "https://github.com/benitamags/codebrief/blob/main/backend/src/api/routes/sse.routes.ts"
click node_analysis_queue "https://github.com/benitamags/codebrief/blob/main/backend/src/queue/analyze.queue.ts"
click node_analysis_worker "https://github.com/benitamags/codebrief/blob/main/backend/src/workers/analyze.worker.ts"
click node_source_analysis "https://github.com/benitamags/codebrief/blob/main/backend/src/lib/ast.ts"
click node_orchestrator "https://github.com/benitamags/codebrief/blob/main/backend/src/agents/orchestrator.ts"
click node_cartographer "https://github.com/benitamags/codebrief/blob/main/backend/src/agents/cartographer.agent.ts"
click node_prioritizer "https://github.com/benitamags/codebrief/blob/main/backend/src/agents/prioritizer.agent.ts"
click node_summarizer "https://github.com/benitamags/codebrief/blob/main/backend/src/agents/summarizer.agent.ts"
click node_guide "https://github.com/benitamags/codebrief/blob/main/backend/src/agents/guide.agent.ts"
click node_rag "https://github.com/benitamags/codebrief/blob/main/backend/src/services/rag.service.ts"
click node_vector "https://github.com/benitamags/codebrief/blob/main/backend/src/services/vector.service.ts"
click node_postgres "https://github.com/benitamags/codebrief/blob/main/backend/src/db/schema.ts"
click node_neo4j "https://github.com/benitamags/codebrief/blob/main/backend/src/services/neo4j.service.ts"
click node_github "https://github.com/benitamags/codebrief/blob/main/backend/src/services/github.service.ts"
click node_progress "https://github.com/benitamags/codebrief/blob/main/backend/src/services/progress.service.ts"
click node_sse_service "https://github.com/benitamags/codebrief/blob/main/backend/src/services/sse.service.ts"
click node_llm "https://github.com/benitamags/codebrief/blob/main/backend/src/lib/llm.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_repo_views,node_visualizations,node_api_client toneBlue
class node_backend_entry,node_repo_api,node_graph_api,node_sse_api toneAmber
class node_analysis_queue,node_analysis_worker,node_source_analysis,node_orchestrator,node_cartographer,node_prioritizer,node_summarizer,node_guide,node_rag,node_progress,node_sse_service,node_llm toneMint
class node_vector,node_postgres,node_neo4j,node_github toneRose
```

## Components

### Next.js Frontend

- [Repository submission](https://github.com/benitamags/codebrief/blob/main/frontend/app/page.tsx): Next.js route · `frontend/app/page.tsx`
- [Repository views](https://github.com/benitamags/codebrief/blob/main/frontend/app/repo/%5Bid%5D/page.tsx): Next.js routes · Overview, architecture, mind map, and reading order screens. · `frontend/app/repo/[id]/page.tsx`
- [Code visualizations](https://github.com/benitamags/codebrief/blob/main/frontend/app/components/code-canvas.tsx): React components · `frontend/app/components/code-canvas.tsx`
- [Backend API client](https://github.com/benitamags/codebrief/blob/main/frontend/app/lib/api.ts): transport boundary · `frontend/app/lib/api.ts`

### Backend API

- [Backend server](https://github.com/benitamags/codebrief/blob/main/backend/src/index.ts): application entry · `backend/src/index.ts`
- [Repository API](https://github.com/benitamags/codebrief/blob/main/backend/src/api/routes/repo.routes.ts): HTTP routes · Accepts repository intake requests. · `backend/src/api/routes/repo.routes.ts`
- [Graph API](https://github.com/benitamags/codebrief/blob/main/backend/src/api/routes/graph.routes.ts): HTTP routes · Serves architecture, chat, and reading-plan results. · `backend/src/api/routes/graph.routes.ts`
- [SSE API](https://github.com/benitamags/codebrief/blob/main/backend/src/api/routes/sse.routes.ts): HTTP routes · `backend/src/api/routes/sse.routes.ts`

### Analysis & AI Pipeline

- [Analysis queue](https://github.com/benitamags/codebrief/blob/main/backend/src/queue/analyze.queue.ts): async job boundary · `backend/src/queue/analyze.queue.ts`
- [Analysis worker](https://github.com/benitamags/codebrief/blob/main/backend/src/workers/analyze.worker.ts): background worker · Clones, parses, indexes, and enriches submitted repositories. · `backend/src/workers/analyze.worker.ts`
- [AST analysis](https://github.com/benitamags/codebrief/blob/main/backend/src/lib/ast.ts): code extraction · `backend/src/lib/ast.ts`
- [Agent orchestrator](https://github.com/benitamags/codebrief/blob/main/backend/src/agents/orchestrator.ts): multi-agent coordinator · `backend/src/agents/orchestrator.ts`
- [Cartography agent](https://github.com/benitamags/codebrief/blob/main/backend/src/agents/cartographer.agent.ts): structure mapping agent · `backend/src/agents/cartographer.agent.ts`
- [Prioritization agent](https://github.com/benitamags/codebrief/blob/main/backend/src/agents/prioritizer.agent.ts): analysis agent · `backend/src/agents/prioritizer.agent.ts`
- [Summarization agent](https://github.com/benitamags/codebrief/blob/main/backend/src/agents/summarizer.agent.ts): analysis agent · `backend/src/agents/summarizer.agent.ts`
- [Guidance agent](https://github.com/benitamags/codebrief/blob/main/backend/src/agents/guide.agent.ts): interactive agent · `backend/src/agents/guide.agent.ts`
- [RAG retrieval](https://github.com/benitamags/codebrief/blob/main/backend/src/services/rag.service.ts): evidence service · `backend/src/services/rag.service.ts`
- [Progress publishing](https://github.com/benitamags/codebrief/blob/main/backend/src/services/progress.service.ts): live status service · `backend/src/services/progress.service.ts`
- [SSE publisher](https://github.com/benitamags/codebrief/blob/main/backend/src/services/sse.service.ts): event delivery service · `backend/src/services/sse.service.ts`
- [LLM & embeddings](https://github.com/benitamags/codebrief/blob/main/backend/src/lib/llm.ts): AI provider abstraction · `backend/src/lib/llm.ts`

### Data & External Systems

- [Vector store service](https://github.com/benitamags/codebrief/blob/main/backend/src/services/vector.service.ts): embedding retrieval · `backend/src/services/vector.service.ts`
- [PostgreSQL](https://github.com/benitamags/codebrief/blob/main/backend/src/db/schema.ts): system of record · Repository records and derived relational data. · `backend/src/db/schema.ts`
- [Neo4j code graph](https://github.com/benitamags/codebrief/blob/main/backend/src/services/neo4j.service.ts): relationship store · `backend/src/services/neo4j.service.ts`
- [GitHub acquisition](https://github.com/benitamags/codebrief/blob/main/backend/src/services/github.service.ts): repository source · `backend/src/services/github.service.ts`

## Connections

- 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