# saranyanalluri/codebasebrain architecture

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

- Interactive diagram: https://gitdiagram.com/saranyanalluri/codebasebrain
- Repository: https://github.com/saranyanalluri/codebasebrain

## Overview

CodebaseBrain answers natural-language questions about an indexed codebase, with Flask-specific query expansions visible in the sampled code. The principal workflow is query input, hybrid retrieval, context construction, then LLM answer generation. Retrieval combines lexical, semantic, and code-graph results, adds identifier matching, and attaches evidence-based explanations. The tree also indicates a separate code-analysis and indexing subsystem, represented here by its named modules and index artifacts; their internal call wiring was not sampled. Provider integrations are optional.

Main entry points: [`app/hybrid_retriever.py`](https://github.com/saranyanalluri/codebasebrain/blob/main/app/hybrid_retriever.py) (Hybrid Retriever), [`app/main.py`](https://github.com/saranyanalluri/codebasebrain/blob/main/app/main.py) (Query CLI), [`app/llm/factory.py`](https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/factory.py) (Provider Factory), [`app/semantic_retriever.py`](https://github.com/saranyanalluri/codebasebrain/blob/main/app/semantic_retriever.py) (Semantic Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Code Analysis"]
  node_inspector["Repository Inspector"]
  node_code_analysis["Code Analyzer<br/>[code_analyzer.py]"]
  node_calls["Call Analysis<br/>[call_analyzer.py]"]
  node_resolve_calls["Call Resolution<br/>[call_resolver.py]"]
  node_imports["Import Analysis<br/>[import_analyzer.py]"]
  node_graph_build["Graph Builder<br/>[graph_builder.py]"]
  node_symbols["Symbol Table<br/>[symbol_table.py]"]
end

subgraph group_retrieval["Hybrid Retrieval"]
  node_hybrid["Hybrid Retriever"]
  node_expand["Query Expansion<br/>[query_expander.py]"]
  node_bm25["BM25 Search<br/>[bm25_retriever.py]"]
  node_semantic["Semantic Search"]
  node_graph_search["Graph Search<br/>[graph_retriever.py]"]
  node_identifier["Identifier Matching"]
  node_explain["Result Explanation"]
end

subgraph group_answer["Answer Generation"]
  node_cli["Query CLI<br/>[main.py]"]
  node_context["Context Builder<br/>[context_builder.py]"]
  node_generator["LLM Answer Generator"]
  node_provider_factory["Provider Factory<br/>[factory.py]"]
  node_local_provider["Local Provider<br/>[local_provider.py]"]
  node_openai_provider["OpenAI Provider<br/>[openai_provider.py]"]
  node_claude_provider["Claude Provider<br/>[claude_provider.py]"]
end

subgraph group_indexes["Search Indexes"]
  node_documents["Code Documents"]
  node_graph_index["Code Graph<br/>[code_graph.json]"]
  node_embedding_index[("Semantic Embeddings")]
end

node_user(("Questioner"))
node_local_service{{"Local LLM Server"}}
node_openai_service{{"OpenAI API"}}
node_claude_service{{"Claude API"}}

node_user -->|"asks"| node_cli
node_cli -->|"searches"| node_hybrid
node_hybrid -->|"expands query"| node_expand
node_hybrid -->|"runs lexical search"| node_bm25
node_hybrid -->|"runs semantic search"| node_semantic
node_hybrid -->|"retrieves graph neighbors"| node_graph_search
node_hybrid -->|"scores identifiers"| node_identifier
node_hybrid -->|"explains results"| node_explain
node_bm25 -->|"reads documents"| node_documents
node_semantic -->|"reads documents"| node_documents
node_semantic -->|"loads embeddings"| node_embedding_index
node_graph_search -->|"reads graph"| node_graph_index
node_hybrid -->|"provides results"| node_context
node_cli -->|"builds context"| node_context
node_cli -->|"generates answer"| node_generator
node_generator -->|"selects provider"| node_provider_factory
node_provider_factory -->|"creates"| node_local_provider
node_provider_factory -->|"creates"| node_openai_provider
node_provider_factory -->|"creates"| node_claude_provider
node_local_provider -.->|"posts prompt"| node_local_service
node_openai_provider -.->|"sends prompt"| node_openai_service
node_claude_provider -.->|"sends prompt"| node_claude_service
node_code_analysis --> node_calls

click node_cli "https://github.com/saranyanalluri/codebasebrain/blob/main/app/main.py"
click node_inspector "https://github.com/saranyanalluri/codebasebrain/blob/main/app/repository_inspector.py"
click node_code_analysis "https://github.com/saranyanalluri/codebasebrain/blob/main/app/code_analyzer.py"
click node_calls "https://github.com/saranyanalluri/codebasebrain/blob/main/app/call_analyzer.py"
click node_resolve_calls "https://github.com/saranyanalluri/codebasebrain/blob/main/app/call_resolver.py"
click node_imports "https://github.com/saranyanalluri/codebasebrain/blob/main/app/import_analyzer.py"
click node_graph_build "https://github.com/saranyanalluri/codebasebrain/blob/main/app/graph_builder.py"
click node_symbols "https://github.com/saranyanalluri/codebasebrain/blob/main/app/symbol_table.py"
click node_hybrid "https://github.com/saranyanalluri/codebasebrain/blob/main/app/hybrid_retriever.py"
click node_expand "https://github.com/saranyanalluri/codebasebrain/blob/main/app/query_expander.py"
click node_bm25 "https://github.com/saranyanalluri/codebasebrain/blob/main/app/bm25_retriever.py"
click node_semantic "https://github.com/saranyanalluri/codebasebrain/blob/main/app/semantic_retriever.py"
click node_graph_search "https://github.com/saranyanalluri/codebasebrain/blob/main/app/graph_retriever.py"
click node_identifier "https://github.com/saranyanalluri/codebasebrain/blob/main/app/identifier_matcher.py"
click node_explain "https://github.com/saranyanalluri/codebasebrain/blob/main/app/explanation_engine.py"
click node_context "https://github.com/saranyanalluri/codebasebrain/blob/main/app/context_builder.py"
click node_generator "https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm_answer_generator.py"
click node_provider_factory "https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/factory.py"
click node_local_provider "https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/local_provider.py"
click node_openai_provider "https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/openai_provider.py"
click node_claude_provider "https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/claude_provider.py"
click node_documents "https://github.com/saranyanalluri/codebasebrain/blob/main/data/indexes/code_documents.json"
click node_graph_index "https://github.com/saranyanalluri/codebasebrain/blob/main/data/indexes/code_graph.json"
click node_embedding_index "https://github.com/saranyanalluri/codebasebrain/blob/main/data/indexes/semantic_embeddings.npy"

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_inspector,node_code_analysis,node_calls,node_resolve_calls,node_imports,node_graph_build,node_symbols toneBlue
class node_hybrid,node_expand,node_bm25,node_semantic,node_graph_search,node_identifier,node_explain toneAmber
class node_cli,node_context,node_generator,node_provider_factory,node_local_provider,node_openai_provider,node_claude_provider,node_local_service,node_openai_service,node_claude_service toneMint
class node_documents,node_graph_index,node_embedding_index toneRose
class node_user toneIndigo
```

## Components

### Code Analysis

- [Repository Inspector](https://github.com/saranyanalluri/codebasebrain/blob/main/app/repository_inspector.py): `app/repository_inspector.py`
- [Code Analyzer](https://github.com/saranyanalluri/codebasebrain/blob/main/app/code_analyzer.py): `app/code_analyzer.py`
- [Call Analysis](https://github.com/saranyanalluri/codebasebrain/blob/main/app/call_analyzer.py): `app/call_analyzer.py`
- [Call Resolution](https://github.com/saranyanalluri/codebasebrain/blob/main/app/call_resolver.py): `app/call_resolver.py`
- [Import Analysis](https://github.com/saranyanalluri/codebasebrain/blob/main/app/import_analyzer.py): `app/import_analyzer.py`
- [Graph Builder](https://github.com/saranyanalluri/codebasebrain/blob/main/app/graph_builder.py): `app/graph_builder.py`
- [Symbol Table](https://github.com/saranyanalluri/codebasebrain/blob/main/app/symbol_table.py): `app/symbol_table.py`

### Hybrid Retrieval

- [Hybrid Retriever](https://github.com/saranyanalluri/codebasebrain/blob/main/app/hybrid_retriever.py): `app/hybrid_retriever.py`
- [Query Expansion](https://github.com/saranyanalluri/codebasebrain/blob/main/app/query_expander.py): `app/query_expander.py`
- [BM25 Search](https://github.com/saranyanalluri/codebasebrain/blob/main/app/bm25_retriever.py): `app/bm25_retriever.py`
- [Semantic Search](https://github.com/saranyanalluri/codebasebrain/blob/main/app/semantic_retriever.py): `app/semantic_retriever.py`
- [Graph Search](https://github.com/saranyanalluri/codebasebrain/blob/main/app/graph_retriever.py): `app/graph_retriever.py`
- [Identifier Matching](https://github.com/saranyanalluri/codebasebrain/blob/main/app/identifier_matcher.py): `app/identifier_matcher.py`
- [Result Explanation](https://github.com/saranyanalluri/codebasebrain/blob/main/app/explanation_engine.py): `app/explanation_engine.py`

### Answer Generation

- [Query CLI](https://github.com/saranyanalluri/codebasebrain/blob/main/app/main.py): `app/main.py`
- [Context Builder](https://github.com/saranyanalluri/codebasebrain/blob/main/app/context_builder.py): `app/context_builder.py`
- [LLM Answer Generator](https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm_answer_generator.py): `app/llm_answer_generator.py`
- [Provider Factory](https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/factory.py): `app/llm/factory.py`
- [Local Provider](https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/local_provider.py): `app/llm/local_provider.py`
- [OpenAI Provider](https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/openai_provider.py): `app/llm/openai_provider.py`
- [Claude Provider](https://github.com/saranyanalluri/codebasebrain/blob/main/app/llm/claude_provider.py): `app/llm/claude_provider.py`

### Search Indexes

- [Code Documents](https://github.com/saranyanalluri/codebasebrain/blob/main/data/indexes/code_documents.json): `data/indexes/code_documents.json`
- [Code Graph](https://github.com/saranyanalluri/codebasebrain/blob/main/data/indexes/code_graph.json): `data/indexes/code_graph.json`
- [Semantic Embeddings](https://github.com/saranyanalluri/codebasebrain/blob/main/data/indexes/semantic_embeddings.npy): `data/indexes/semantic_embeddings.npy`

### Other components

- **Questioner**
- **Local LLM Server**
- **OpenAI API**
- **Claude API**

## Connections

- Questioner → Query CLI: asks
- Query CLI → Hybrid Retriever: searches
- Hybrid Retriever → Query Expansion: expands query
- Hybrid Retriever → BM25 Search: runs lexical search
- Hybrid Retriever → Semantic Search: runs semantic search
- Hybrid Retriever → Graph Search: retrieves graph neighbors
- Hybrid Retriever → Identifier Matching: scores identifiers
- Hybrid Retriever → Result Explanation: explains results
- BM25 Search → Code Documents: reads documents
- Semantic Search → Code Documents: reads documents
- Semantic Search → Semantic Embeddings: loads embeddings
- Graph Search → Code Graph: reads graph
- Hybrid Retriever → Context Builder: provides results
- Query CLI → Context Builder: builds context
- Query CLI → LLM Answer Generator: generates answer
- LLM Answer Generator → Provider Factory: selects provider
- Provider Factory → Local Provider: creates
- Provider Factory → OpenAI Provider: creates
- Provider Factory → Claude Provider: creates
- Local Provider → Local LLM Server: posts prompt
- OpenAI Provider → OpenAI API: sends prompt
- Claude Provider → Claude API: sends prompt
- Code Analyzer → Call Analysis