# anjali-2310176/ai-codebase-explainer architecture

> Architecture diagram of the GitHub repository anjali-2310176/ai-codebase-explainer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anjali-2310176/ai-codebase-explainer
- Repository: https://github.com/anjali-2310176/ai-codebase-explainer

## Overview

AI Codebase Explainer lets a user submit a public Python repository, follow its analysis job, then search indexed code and view retrieved sources. Ingestion clones the repository, parses Python entities and relations, and stores searchable chunks and graph data; the app also exposes repository summaries and diagrams. Retrieval and answer generation are documented as offline-capable, with Gemini optional. The graph follows sampled route, pipeline, parser, embedding, and application code; links for unsampled agent and presentation features follow README documentation.

Main entry points: [`backend/app/api/routes.py`](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/api/routes.py) (REST routes), [`backend/app/services/pipeline.py`](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/pipeline.py) (Ingestion pipeline), [`backend/app/db/session.py`](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/db/session.py) (Database sessions), [`frontend/src/App.tsx`](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/frontend/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_ui["React application<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and jobs"]
  node_routes["REST routes<br/>[routes.py]"]
  node_queue["Job queue<br/>[queue.py]"]
end

subgraph group_ingest["Repository analysis"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_clone["Repository clone<br/>[clone.py]"]
  node_parser["Python parser<br/>[python_parser.py]"]
  node_file_safety["Safe file reading<br/>[file_safety.py]"]
  node_entities["Code entities<br/>[entities.py]"]
  node_graph["Code graph<br/>[graph.py]"]
  node_embed["Chunk indexing<br/>[embeddings.py]"]
end

subgraph group_query["Search and explain"]
  node_agent["Retrieval answers<br/>[agent.py]"]
  node_llm["LLM provider<br/>[llm_provider.py]"]
  node_summaries["README and diagrams<br/>[routes.py]"]
end

subgraph group_state["Persistent state"]
  node_db_models["Repository records<br/>[models.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_sqlite[("SQLite database")]
end

node_user(("Repository explorer"))
node_github["GitHub repository"]
node_gemini["Gemini API"]

node_user -->|"submits and views"| node_ui
node_ui -->|"invokes"| node_api_client
node_api_client -->|"HTTP requests"| node_routes
node_routes -->|"enqueues jobs"| node_queue
node_routes -->|"starts ingestion"| node_pipeline
node_queue -->|"runs job"| node_pipeline
node_pipeline -->|"clones and scans"| node_clone
node_clone -->|"fetches repository"| node_github
node_pipeline -->|"parses files"| node_parser
node_parser -->|"reads safely"| node_file_safety
node_parser -->|"creates entities"| node_entities
node_pipeline -->|"upserts relations"| node_graph
node_pipeline -->|"stores chunks"| node_embed
node_pipeline -->|"updates job and repository"| node_db_session
node_graph -->|"persists graph"| node_db_session
node_embed -->|"reads and writes chunks"| node_db_session
node_db_session -->|"uses models"| node_db_models
node_db_session -->|"queries"| node_sqlite
node_routes -->|"reads job and repository"| node_db_session
node_ui -->|"asks code question"| node_agent
node_agent -->|"retrieves chunks"| node_embed
node_agent -->|"formats answer"| node_llm
node_llm -.->|"generates optionally"| node_gemini
node_routes -->|"generates README and diagrams"| node_summaries
node_ui -->|"requests summaries and diagrams"| node_summaries
node_routes -->|"serves graph view"| node_graph
node_ui -->|"polls job and repository"| node_routes

click node_ui "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/frontend/src/api.ts"
click node_routes "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/api/routes.py"
click node_queue "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/jobs/queue.py"
click node_pipeline "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/pipeline.py"
click node_clone "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/clone.py"
click node_parser "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/parser/python_parser.py"
click node_file_safety "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/security/file_safety.py"
click node_entities "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/entities.py"
click node_graph "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/graph.py"
click node_embed "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/embeddings.py"
click node_agent "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/agent.py"
click node_llm "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/llm_provider.py"
click node_summaries "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/api/routes.py"
click node_db_models "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/db/models.py"
click node_db_session "https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/db/session.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_ui,node_api_client toneBlue
class node_routes,node_queue toneAmber
class node_pipeline,node_clone,node_parser,node_file_safety,node_entities,node_graph,node_embed,node_gemini toneMint
class node_agent,node_llm,node_summaries toneRose
class node_db_models,node_db_session,node_sqlite,node_user,node_github toneIndigo
```

## Components

### User interface

- [React application](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and jobs

- [REST routes](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Job queue](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/jobs/queue.py): `backend/app/services/jobs/queue.py`

### Repository analysis

- [Ingestion pipeline](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/pipeline.py): `backend/app/services/pipeline.py`
- [Repository clone](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/clone.py): `backend/app/services/clone.py`
- [Python parser](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/parser/python_parser.py): `backend/app/services/parser/python_parser.py`
- [Safe file reading](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/security/file_safety.py): `backend/app/security/file_safety.py`
- [Code entities](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/entities.py): `backend/app/services/entities.py`
- [Code graph](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/graph.py): `backend/app/services/graph.py`
- [Chunk indexing](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`

### Search and explain

- [Retrieval answers](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/agent.py): `backend/app/services/agent.py`
- [LLM provider](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/services/llm_provider.py): `backend/app/services/llm_provider.py`
- [README and diagrams](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`

### Persistent state

- [Repository records](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Database sessions](https://github.com/anjali-2310176/ai-codebase-explainer/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- **SQLite database**

### Other components

- **Repository explorer**
- **GitHub repository**
- **Gemini API**

## Connections

- Repository explorer → React application: submits and views
- React application → API client: invokes
- API client → REST routes: HTTP requests
- REST routes → Job queue: enqueues jobs
- REST routes → Ingestion pipeline: starts ingestion
- Job queue → Ingestion pipeline: runs job
- Ingestion pipeline → Repository clone: clones and scans
- Repository clone → GitHub repository: fetches repository
- Ingestion pipeline → Python parser: parses files
- Python parser → Safe file reading: reads safely
- Python parser → Code entities: creates entities
- Ingestion pipeline → Code graph: upserts relations
- Ingestion pipeline → Chunk indexing: stores chunks
- Ingestion pipeline → Database sessions: updates job and repository
- Code graph → Database sessions: persists graph
- Chunk indexing → Database sessions: reads and writes chunks
- Database sessions → Repository records: uses models
- Database sessions → SQLite database: queries
- REST routes → Database sessions: reads job and repository
- React application → Retrieval answers: asks code question
- Retrieval answers → Chunk indexing: retrieves chunks
- Retrieval answers → LLM provider: formats answer
- LLM provider → Gemini API: generates optionally
- REST routes → README and diagrams: generates README and diagrams
- React application → README and diagrams: requests summaries and diagrams
- REST routes → Code graph: serves graph view
- React application → REST routes: polls job and repository