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.