deepak-menan-r/repoai

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.