# jayasuriyasr/codeatlas architecture

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

- Interactive diagram: https://gitdiagram.com/jayasuriyasr/codeatlas
- Repository: https://github.com/jayasuriyasr/codeatlas

## Overview

SEI is a repository-level GraphRAG investigation engine for Python/Django and TypeScript/Next.js codebases. Its main workflow indexes source into a Neo4j symbol graph and embeddings, routes developer questions to structural, semantic, or trace retrieval, packs relevant code into model context, then streams a cited answer with grounding checks. The graph reflects documented capabilities and the sampled query/indexing seams; several internals and integrations are represented only at directory level because their implementations were not excerpted.

Main entry points: [`index/indexer.py`](https://github.com/jayasuriyasr/codeatlas/blob/main/index/indexer.py) (Index coordinator), [`api/app.py`](https://github.com/jayasuriyasr/codeatlas/blob/main/api/app.py) (Investigation API), [`api/cli.py`](https://github.com/jayasuriyasr/codeatlas/blob/main/api/cli.py) (CLI wiring), [`retrieve/router.py`](https://github.com/jayasuriyasr/codeatlas/blob/main/retrieve/router.py) (Query router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Source indexing"]
  node_indexer["Index coordinator<br/>[indexer.py]"]
  node_pyadapter["Python parser<br/>[python.py]"]
  node_tsadapter["TypeScript parser<br/>[typescript.py]"]
  node_symbolmodel["Symbol model<br/>[base.py]"]
  node_chunker["Chunk and scrub<br/>[chunker.py]"]
  node_cache[("Embedding cache<br/>[cache.py]")]
  node_providers["Embedding providers<br/>[providers.py]"]
  node_moves["Move detection<br/>[moves.py]"]
end

subgraph group_store["Graph and retrieval"]
  node_writer["Graph writer<br/>[writer.py]"]
  node_reader["Graph reader<br/>[reader.py]"]
  node_neo4j[("Neo4j")]
end

subgraph group_answer["Answer generation"]
  node_router["Query router<br/>[router.py]"]
  node_retrieval["Hybrid retrieval"]
  node_frames["Frame resolution<br/>[frames.py]"]
  node_packer["Context packer<br/>[packer.py]"]
  node_renderer["Code renderer<br/>[render.py]"]
  node_stream["Answer streaming<br/>[stream.py]"]
  node_grounding["Grounding checks<br/>[validate.py]"]
  node_classifier["Claim classifier<br/>[classify.py]"]
end

subgraph group_ops["API and evaluation"]
  node_api["Investigation API<br/>[app.py]"]
  node_cli["CLI wiring<br/>[cli.py]"]
  node_metrics["Runtime metrics<br/>[metrics.py]"]
  node_evaluation["Evaluation harness<br/>[harness.py]"]
end

node_developer(("Developer"))
node_repo["Code repository"]

node_developer -->|"asks question"| node_api
node_api -->|"routes query"| node_router
node_api -->|"packs context"| node_packer
node_api -->|"validates answer"| node_grounding
node_api -->|"streams events"| node_stream
node_cli -->|"configures indexing"| node_indexer
node_cli -->|"configures service"| node_api
node_repo -.->|"provides source"| node_indexer
node_indexer -->|"parses Python"| node_pyadapter
node_indexer -.->|"supports TypeScript"| node_tsadapter
node_indexer -->|"builds chunks"| node_chunker
node_indexer -->|"embeds through"| node_cache
node_indexer -.->|"uses provider"| node_providers
node_indexer -->|"collects moves"| node_moves
node_pyadapter -->|"produces symbols"| node_symbolmodel
node_tsadapter -.->|"produces symbols"| node_symbolmodel
node_cli -->|"configures writer"| node_writer
node_writer -->|"writes graph"| node_neo4j
node_cli -->|"configures reader"| node_reader
node_reader -.->|"reads graph"| node_neo4j
node_router -.->|"selects retrieval"| node_retrieval
node_router -.->|"resolves trace"| node_frames
node_api -.->|"retrieves candidates"| node_retrieval
node_packer -->|"renders blocks"| node_renderer
node_stream -->|"classifies claims"| node_classifier
node_grounding -->|"uses classification"| node_classifier
node_evaluation -->|"checks metrics"| node_metrics

click node_api "https://github.com/jayasuriyasr/codeatlas/blob/main/api/app.py"
click node_cli "https://github.com/jayasuriyasr/codeatlas/blob/main/api/cli.py"
click node_indexer "https://github.com/jayasuriyasr/codeatlas/blob/main/index/indexer.py"
click node_pyadapter "https://github.com/jayasuriyasr/codeatlas/blob/main/adapters/python.py"
click node_tsadapter "https://github.com/jayasuriyasr/codeatlas/blob/main/adapters/typescript.py"
click node_symbolmodel "https://github.com/jayasuriyasr/codeatlas/blob/main/adapters/base.py"
click node_chunker "https://github.com/jayasuriyasr/codeatlas/blob/main/index/chunker.py"
click node_cache "https://github.com/jayasuriyasr/codeatlas/blob/main/index/cache.py"
click node_providers "https://github.com/jayasuriyasr/codeatlas/blob/main/index/providers.py"
click node_moves "https://github.com/jayasuriyasr/codeatlas/blob/main/index/moves.py"
click node_writer "https://github.com/jayasuriyasr/codeatlas/blob/main/graph/writer.py"
click node_reader "https://github.com/jayasuriyasr/codeatlas/blob/main/graph/reader.py"
click node_router "https://github.com/jayasuriyasr/codeatlas/blob/main/retrieve/router.py"
click node_retrieval "https://github.com/jayasuriyasr/codeatlas/tree/main/retrieve"
click node_frames "https://github.com/jayasuriyasr/codeatlas/blob/main/retrieve/frames.py"
click node_packer "https://github.com/jayasuriyasr/codeatlas/blob/main/pack/packer.py"
click node_renderer "https://github.com/jayasuriyasr/codeatlas/blob/main/pack/render.py"
click node_stream "https://github.com/jayasuriyasr/codeatlas/blob/main/api/stream.py"
click node_grounding "https://github.com/jayasuriyasr/codeatlas/blob/main/ground/validate.py"
click node_classifier "https://github.com/jayasuriyasr/codeatlas/blob/main/ground/classify.py"
click node_metrics "https://github.com/jayasuriyasr/codeatlas/blob/main/metrics.py"
click node_evaluation "https://github.com/jayasuriyasr/codeatlas/blob/main/eval/harness.py"

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_indexer,node_pyadapter,node_tsadapter,node_symbolmodel,node_chunker,node_cache,node_providers,node_moves toneBlue
class node_writer,node_reader,node_neo4j toneAmber
class node_router,node_retrieval,node_frames,node_packer,node_renderer,node_stream,node_grounding,node_classifier toneMint
class node_api,node_cli,node_metrics,node_evaluation toneRose
class node_developer,node_repo toneIndigo
```

## Components

### Source indexing

- [Index coordinator](https://github.com/jayasuriyasr/codeatlas/blob/main/index/indexer.py): `index/indexer.py`
- [Python parser](https://github.com/jayasuriyasr/codeatlas/blob/main/adapters/python.py): `adapters/python.py`
- [TypeScript parser](https://github.com/jayasuriyasr/codeatlas/blob/main/adapters/typescript.py): `adapters/typescript.py`
- [Symbol model](https://github.com/jayasuriyasr/codeatlas/blob/main/adapters/base.py): `adapters/base.py`
- [Chunk and scrub](https://github.com/jayasuriyasr/codeatlas/blob/main/index/chunker.py): `index/chunker.py`
- [Embedding cache](https://github.com/jayasuriyasr/codeatlas/blob/main/index/cache.py): `index/cache.py`
- [Embedding providers](https://github.com/jayasuriyasr/codeatlas/blob/main/index/providers.py): `index/providers.py`
- [Move detection](https://github.com/jayasuriyasr/codeatlas/blob/main/index/moves.py): `index/moves.py`

### Graph and retrieval

- [Graph writer](https://github.com/jayasuriyasr/codeatlas/blob/main/graph/writer.py): `graph/writer.py`
- [Graph reader](https://github.com/jayasuriyasr/codeatlas/blob/main/graph/reader.py): `graph/reader.py`
- **Neo4j**

### Answer generation

- [Query router](https://github.com/jayasuriyasr/codeatlas/blob/main/retrieve/router.py): `retrieve/router.py`
- [Hybrid retrieval](https://github.com/jayasuriyasr/codeatlas/tree/main/retrieve): `retrieve`
- [Frame resolution](https://github.com/jayasuriyasr/codeatlas/blob/main/retrieve/frames.py): `retrieve/frames.py`
- [Context packer](https://github.com/jayasuriyasr/codeatlas/blob/main/pack/packer.py): `pack/packer.py`
- [Code renderer](https://github.com/jayasuriyasr/codeatlas/blob/main/pack/render.py): `pack/render.py`
- [Answer streaming](https://github.com/jayasuriyasr/codeatlas/blob/main/api/stream.py): `api/stream.py`
- [Grounding checks](https://github.com/jayasuriyasr/codeatlas/blob/main/ground/validate.py): `ground/validate.py`
- [Claim classifier](https://github.com/jayasuriyasr/codeatlas/blob/main/ground/classify.py): `ground/classify.py`

### API and evaluation

- [Investigation API](https://github.com/jayasuriyasr/codeatlas/blob/main/api/app.py): `api/app.py`
- [CLI wiring](https://github.com/jayasuriyasr/codeatlas/blob/main/api/cli.py): `api/cli.py`
- [Runtime metrics](https://github.com/jayasuriyasr/codeatlas/blob/main/metrics.py): `metrics.py`
- [Evaluation harness](https://github.com/jayasuriyasr/codeatlas/blob/main/eval/harness.py): `eval/harness.py`

### Other components

- **Developer**
- **Code repository**

## Connections

- Developer → Investigation API: asks question (evidence: `api/app.py`)
- Investigation API → Query router: routes query (evidence: `api/app.py`)
- Investigation API → Context packer: packs context (evidence: `api/app.py`)
- Investigation API → Grounding checks: validates answer (evidence: `api/app.py`)
- Investigation API → Answer streaming: streams events (evidence: `api/app.py`)
- CLI wiring → Index coordinator: configures indexing (evidence: `api/cli.py`)
- CLI wiring → Investigation API: configures service (evidence: `api/cli.py`)
- Code repository → Index coordinator: provides source (evidence: `README.md`)
- Index coordinator → Python parser: parses Python (evidence: `index/indexer.py`)
- Index coordinator → TypeScript parser: supports TypeScript (evidence: `README.md`)
- Index coordinator → Chunk and scrub: builds chunks (evidence: `index/indexer.py`)
- Index coordinator → Embedding cache: embeds through (evidence: `index/indexer.py`)
- Index coordinator → Embedding providers: uses provider
- Index coordinator → Move detection: collects moves (evidence: `index/indexer.py`)
- Python parser → Symbol model: produces symbols (evidence: `adapters/python.py`)
- TypeScript parser → Symbol model: produces symbols (evidence: `README.md`)
- CLI wiring → Graph writer: configures writer (evidence: `api/cli.py`)
- Graph writer → Neo4j: writes graph (evidence: `graph/writer.py`)
- CLI wiring → Graph reader: configures reader (evidence: `api/cli.py`)
- Graph reader → Neo4j: reads graph
- Query router → Hybrid retrieval: selects retrieval (evidence: `retrieve/router.py`)
- Query router → Frame resolution: resolves trace (evidence: `retrieve/router.py`)
- Investigation API → Hybrid retrieval: retrieves candidates (evidence: `api/app.py`)
- Context packer → Code renderer: renders blocks (evidence: `pack/packer.py`)
- Answer streaming → Claim classifier: classifies claims (evidence: `api/stream.py`)
- Grounding checks → Claim classifier: uses classification (evidence: `ground/validate.py`)
- Evaluation harness → Runtime metrics: checks metrics
