# deepak-menan-r/repoai architecture

> Architecture diagram of the GitHub repository deepak-menan-r/repoai, 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/deepak-menan-r/repoai
- Repository: https://github.com/deepak-menan-r/repoai

## Overview

#### Purpose and Runtime Surface
This is a scaffolded repository-intelligence backend: it indexes a Git repository into structural graphs and semantic embeddings, then answers natural-language engineering questions with retrieved context and an LLM. The FastAPI application starts at `backend/app/main.py`; HTTP endpoints are defined in `backend/app/api/routes.py`. The included `frontend/index.html` is a minimal browser surface rather than a substantial frontend application.

#### API and Application Control Plane
Routes accept repository-indexing and question-answering requests, delegating long-lived work to the indexing and query layers. Application configuration—including graph backend selection and external credentials—is centralized in `backend/app/config.py`. The effective application boundary is:
`backend/app/main.py` → `backend/app/api/routes.py` → pipeline/query services.

#### Ingestion and Structural Extraction
Repository ingestion begins by cloning a supplied Git URL, then walking eligible files:
- `backend/app/ingestion/repo_cloner.py`
- `backend/app/ingestion/file_walker.py`

Parsing is language-pluggable through a base interface; Python is the first supported language and uses the standard-library AST. The parser extracts source-level entities and relationships used by downstream graph and embedding stages:
- `backend/app/parsing/base.py`
- `backend/app/parsing/python_parser.py`

#### Indexing Orchestration
The indexer is the primary write-side coordinator. It connects cloning, file discovery, parser selection, graph construction, and embedding persistence for a repository. Parser and pipeline components are resolved through a registry, creating a boundary for future language-specific implementations:
- `backend/app/pipeline/indexer.py`
- `backend/app/pipeline/registry.py`

The expected flow is Git URL → local clone → source files → AST-derived entities → graph records plus embedding documents.

#### Knowledge Graph Layer
Graph builders convert extracted entities into call, dependency, API, and documentation relationships. Storage is abstracted so the default embedded implementation can operate without infrastructure, while Neo4j is an optional persistent remote backend:
- `backend/app/graph/builders.py`
- `backend/app/graph/store.py`
- `backend/app/graph/memory_store.py`
- `backend/app/graph/neo4j_client.py`
- `backend/app/graph/factory.py`

The factory is the backend-selection boundary. Neo4j requires configured `NEO4J_*` settings and can be run locally through `docker-compose.yml` or against Aura.

#### Embedding and Retrieval Layer
Structural entities and associated code/documentation text are embedded through OpenAI and persisted in local persistent ChromaDB:
- `backend/app/embeddings/embedder.py`
- `backend/app/embeddings/vector_store.py`

Retrieval classifies query intent, performs graph traversal and vector similarity search, then combines results. This is the read-side boundary between repository stores and answer generation:
- `backend/app/retrieval/intent.py`
- `backend/app/retrieval/graph_retriever.py`
- `backend/app/retrieval/vector_retriever.py`
- `backend/app/retrieval/hybrid.py`

Embedding inputs are currently unchunked; entities exceeding OpenAI’s 8,192-token embedding input limit can fail an indexing batch.

#### Query Answering and External Services
The query engine coordinates intent/retrieval results, formats repository context, and invokes the LLM wrapper:
- `backend/app/query/engine.py`
- `backend/app/llm/client.py`

Material runtime dependencies are Python 3.11+, FastAPI, OpenAI chat and embedding APIs, ChromaDB, and optionally Neo4j. The default deployment needs OpenAI credentials but not Neo4j; graph behavior defaults to the embedded store.

Main entry points: [`backend/app/api/routes.py`](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/api/routes.py) (HTTP routes), [`backend/app/graph/factory.py`](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/factory.py) (Graph store factory), [`backend/app/parsing/python_parser.py`](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/parsing/python_parser.py) (Python AST parser), [`backend/app/embeddings/embedder.py`](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/embeddings/embedder.py) (OpenAI embedder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_main["FastAPI app<br/>application entry<br/>[main.py]"]
  node_routes["HTTP routes<br/>API controller<br/>[routes.py]"]
  node_config["Application config<br/>configuration boundary<br/>[config.py]"]
end

subgraph group_indexing["Repository Indexing"]
  node_indexer["Repository indexer<br/>write coordinator<br/>[indexer.py]"]
  node_registry["Parser registry<br/>component resolver<br/>[registry.py]"]
  node_cloner["Git cloner<br/>ingestion<br/>[repo_cloner.py]"]
  node_walker["Source file walker<br/>ingestion<br/>[file_walker.py]"]
  node_python_parser["Python AST parser<br/>structural extractor<br/>[python_parser.py]"]
end

subgraph group_knowledge["Knowledge Stores"]
  node_graph_builders["Graph builders<br/>graph construction<br/>[builders.py]"]
  node_graph_factory["Graph store factory<br/>backend selector<br/>[factory.py]"]
  node_memory_graph[("Embedded graph store<br/>default graph backend<br/>[memory_store.py]")]
  node_neo4j[("Neo4j graph backend<br/>optional remote graph backend<br/>[neo4j_client.py]")]
  node_embedder["OpenAI embedder<br/>embedding client<br/>[embedder.py]"]
  node_vector_store[("Chroma vector store<br/>embedding persistence<br/>[vector_store.py]")]
end

subgraph group_query["Retrieval &amp; Answers"]
  node_hybrid["Hybrid retrieval<br/>read-side coordinator<br/>[hybrid.py]"]
  node_query_engine["Query engine<br/>answer coordinator<br/>[engine.py]"]
  node_llm["OpenAI LLM client<br/>answer generation<br/>[client.py]"]
end

node_browser["Minimal browser UI<br/>HTML surface<br/>[index.html]"]
node_openai{{"OpenAI APIs<br/>external service"}}

node_browser -->|"HTTP requests"| node_routes
node_main -->|"mounts"| node_routes
node_main -->|"loads"| node_config
node_routes -->|"index repository"| node_indexer
node_routes -->|"answer question"| node_query_engine
node_indexer -->|"clone Git URL"| node_cloner
node_cloner -->|"local clone"| node_walker
node_walker -->|"eligible files"| node_registry
node_registry -->|"select parser"| node_python_parser
node_python_parser -->|"entities and relationships"| node_graph_builders
node_graph_builders -->|"graph records"| node_graph_factory
node_graph_factory -->|"default backend"| node_memory_graph
node_graph_factory -.->|"optional backend"| node_neo4j
node_python_parser -->|"entity text"| node_embedder
node_embedder -->|"embedding documents"| node_vector_store
node_embedder -->|"embeddings"| node_openai
node_query_engine -->|"retrieve context"| node_hybrid
node_hybrid -->|"graph traversal"| node_memory_graph
node_hybrid -->|"similarity search"| node_vector_store
node_query_engine -->|"context and question"| node_llm
node_llm -->|"chat completion"| node_openai
node_config -->|"backend selection"| node_graph_factory

click node_browser "https://github.com/deepak-menan-r/repoai/blob/main/frontend/index.html"
click node_main "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/main.py"
click node_routes "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/api/routes.py"
click node_config "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/config.py"
click node_indexer "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/pipeline/indexer.py"
click node_registry "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/pipeline/registry.py"
click node_cloner "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/ingestion/repo_cloner.py"
click node_walker "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/ingestion/file_walker.py"
click node_python_parser "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/parsing/python_parser.py"
click node_graph_builders "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/builders.py"
click node_graph_factory "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/factory.py"
click node_memory_graph "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/memory_store.py"
click node_neo4j "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/neo4j_client.py"
click node_embedder "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/embeddings/embedder.py"
click node_vector_store "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/embeddings/vector_store.py"
click node_hybrid "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/retrieval/hybrid.py"
click node_query_engine "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/query/engine.py"
click node_llm "https://github.com/deepak-menan-r/repoai/blob/main/backend/app/llm/client.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_main,node_routes,node_config toneBlue
class node_indexer,node_registry,node_cloner,node_walker,node_python_parser toneAmber
class node_graph_builders,node_graph_factory,node_memory_graph,node_neo4j,node_embedder,node_vector_store toneMint
class node_hybrid,node_query_engine,node_llm toneRose
class node_browser,node_openai toneNeutral
```

## Components

### Application API

- [FastAPI app](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/main.py): application entry · `backend/app/main.py`
- [HTTP routes](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/api/routes.py): API controller · `backend/app/api/routes.py`
- [Application config](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/config.py): configuration boundary · Selects graph backend and supplies external credentials. · `backend/app/config.py`

### Repository Indexing

- [Repository indexer](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/pipeline/indexer.py): write coordinator · Coordinates cloning, extraction, graph building, and embedding persistence. · `backend/app/pipeline/indexer.py`
- [Parser registry](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/pipeline/registry.py): component resolver · Resolves language-specific parsers and pipeline components. · `backend/app/pipeline/registry.py`
- [Git cloner](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/ingestion/repo_cloner.py): ingestion · `backend/app/ingestion/repo_cloner.py`
- [Source file walker](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/ingestion/file_walker.py): ingestion · `backend/app/ingestion/file_walker.py`
- [Python AST parser](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/parsing/python_parser.py): structural extractor · Implements the pluggable parser interface using the standard-library AST. · `backend/app/parsing/python_parser.py`

### Knowledge Stores

- [Graph builders](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/builders.py): graph construction · Creates call, dependency, API, and documentation relationships. · `backend/app/graph/builders.py`
- [Graph store factory](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/factory.py): backend selector · Chooses the embedded default or optional Neo4j backend. · `backend/app/graph/factory.py`
- [Embedded graph store](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/memory_store.py): default graph backend · `backend/app/graph/memory_store.py`
- [Neo4j graph backend](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/graph/neo4j_client.py): optional remote graph backend · Requires configured NEO4J_* settings. · `backend/app/graph/neo4j_client.py`
- [OpenAI embedder](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/embeddings/embedder.py): embedding client · Unchunked inputs exceeding 8,192 tokens can fail indexing. · `backend/app/embeddings/embedder.py`
- [Chroma vector store](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/embeddings/vector_store.py): embedding persistence · Local persistent storage for structural and text embeddings. · `backend/app/embeddings/vector_store.py`

### Retrieval & Answers

- [Hybrid retrieval](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/retrieval/hybrid.py): read-side coordinator · Classifies intent and combines graph traversal with vector search. · `backend/app/retrieval/hybrid.py`
- [Query engine](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/query/engine.py): answer coordinator · Formats retrieved repository context for answer generation. · `backend/app/query/engine.py`
- [OpenAI LLM client](https://github.com/deepak-menan-r/repoai/blob/main/backend/app/llm/client.py): answer generation · `backend/app/llm/client.py`

### Other components

- [Minimal browser UI](https://github.com/deepak-menan-r/repoai/blob/main/frontend/index.html): HTML surface · `frontend/index.html`
- **OpenAI APIs**: external service · Provides chat completion and embedding APIs.

## Connections

- Minimal browser UI → HTTP routes: HTTP requests
- FastAPI app → HTTP routes: mounts
- FastAPI app → Application config: loads
- HTTP routes → Repository indexer: index repository
- HTTP routes → Query engine: answer question
- Repository indexer → Git cloner: clone Git URL
- Git cloner → Source file walker: local clone
- Source file walker → Parser registry: eligible files
- Parser registry → Python AST parser: select parser
- Python AST parser → Graph builders: entities and relationships
- Graph builders → Graph store factory: graph records
- Graph store factory → Embedded graph store: default backend
- Graph store factory → Neo4j graph backend: optional backend
- Python AST parser → OpenAI embedder: entity text
- OpenAI embedder → Chroma vector store: embedding documents
- OpenAI embedder → OpenAI APIs: embeddings
- Query engine → Hybrid retrieval: retrieve context
- Hybrid retrieval → Embedded graph store: graph traversal
- Hybrid retrieval → Chroma vector store: similarity search
- Query engine → OpenAI LLM client: context and question
- OpenAI LLM client → OpenAI APIs: chat completion
- Application config → Graph store factory: backend selection