docs/architecture.md

Architecture

Codebase Intelligence Agent is a repository question-answering system. It indexes source files into searchable chunks, retrieves relevant evidence for a user question, and optionally asks Gemini to turn that evidence into a natural answer with citations.

Runtime Components

• Frontend: Streamlit app in frontend/app.py.
• Backend API: FastAPI app in backend/main.py.
• Chunking: Language-aware chunkers in backend/chunking.
• Retrieval: BM25, Qdrant semantic search, and graph boosting in backend/retrieval.
• Vector database: Qdrant Cloud stores embeddings for semantic search.
• Graph store: NetworkX builds dependency graphs and persists them as JSON files under data/graphs.
• LLM: Gemini generates final explanatory answers when GEMINI_API_KEY is configured.

Request Flow

1. The user indexes a local, GitHub, or uploaded repository.
2. The backend parses files and creates Chunk records.
3. BM25 keeps an in-memory lexical index.
4. Qdrant stores chunk embeddings and payload metadata.
5. NetworkX stores dependency graph nodes and relationships locally.
6. On question answering, the backend retrieves candidate chunks.
7. Gemini receives the question plus top retrieved chunks and returns a concise explanation.
8. The API returns the answer, citations, and retrieved chunks to Streamlit.

Storage Responsibilities

System	Responsibility
Qdrant	Vector embeddings and semantic similarity search
NetworkX JSON	Code dependency graph and graph-based retrieval boosts
Backend memory	Current repo summaries and BM25 index
Local data/	Cloned/uploaded repository working files

Important Notes

• localhost works only when Qdrant is running on the same machine as the backend.
• This repo is currently arranged for Qdrant Cloud through .env.
• Dependency graphs are local files, so Neo4j is not required.
• Secrets must live in environment variables or CI/CD secrets, never in Git.