# damaf77/codebase-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/damaf77/codebase-assistant
- Repository: https://github.com/damaf77/codebase-assistant

## Overview

Codebase Maintenance Assistant is a Windows desktop tool for locally indexing Python projects, searching their code, and optionally using retrieval-grounded AI. The main workflow is project selection, AST indexing, SQLite persistence, then search or repository-wide AI questions. Separate analysis branches provide project insights, maintenance smells/import impact, and a static repository map. The excerpts show the indexing worker and provider adapter mechanics; some GUI actions and service connections are supported only by the README or SOURCE INDEX, so unsampled details are not expanded.

Main entry points: [`app/main.py`](https://github.com/damaf77/codebase-assistant/blob/main/app/main.py) (Desktop GUI), [`app/services/ai_provider.py`](https://github.com/damaf77/codebase-assistant/blob/main/app/services/ai_provider.py) (AI orchestration), [`app/providers/common.py`](https://github.com/damaf77/codebase-assistant/blob/main/app/providers/common.py) (Provider HTTP), [`app/services/databases.py`](https://github.com/damaf77/codebase-assistant/blob/main/app/services/databases.py) (Code retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workflow"]
  node_gui["Desktop GUI<br/>[main.py]"]
end

subgraph group_local_index["Local indexing and search"]
  node_indexer["Python indexer<br/>[indexer.py]"]
  node_database[("SQLite code index<br/>[databases.py]")]
  node_retrieval["Code retrieval<br/>[databases.py]"]
  node_retrieval_eval["Retrieval evaluation<br/>[evaluation.py]"]
end

subgraph group_analysis["Project analysis"]
  node_insights["Project insights"]
  node_maintenance["Maintenance analysis"]
  node_impact["Import impact"]
end

subgraph group_ai["AI assistance"]
  node_ai_service["AI orchestration<br/>[ai_provider.py]"]
  node_provider_common["Provider HTTP<br/>[common.py]"]
  node_gemini["Gemini adapter<br/>[gemini.py]"]
  node_groq["Groq adapter<br/>[groq.py]"]
  node_openai["OpenAI adapter<br/>[openai.py]"]
  node_openrouter["OpenRouter adapter<br/>[openrouter.py]"]
  node_providers{{"AI providers"}}
end

subgraph group_mapping["Repository mapping"]
  node_repo_map["Repository map<br/>[repository_map.py]"]
  node_map_eval["Map evaluation"]
end

node_user(("Project user"))

node_user -->|"selects project"| node_gui
node_gui -->|"indexes project"| node_indexer
node_gui -->|"saves chunks"| node_database
node_gui -->|"runs checks"| node_maintenance
node_gui -->|"builds map"| node_repo_map
node_gui -->|"searches index"| node_retrieval
node_retrieval -->|"queries chunks"| node_database
node_gui -->|"requests insights"| node_insights
node_gui -->|"requests impact"| node_impact
node_maintenance -->|"provides import graph"| node_impact
node_gui -->|"asks repository"| node_ai_service
node_ai_service -->|"retrieves context"| node_retrieval
node_ai_service -->|"dispatches to"| node_gemini
node_ai_service -->|"dispatches to"| node_groq
node_ai_service -->|"dispatches to"| node_openai
node_ai_service -->|"dispatches to"| node_openrouter
node_gemini -->|"posts request"| node_provider_common
node_openai -->|"posts request"| node_provider_common
node_openrouter -->|"posts request"| node_provider_common
node_provider_common -->|"sends HTTP"| node_providers
node_gui -.->|"evaluates retrieval"| node_retrieval_eval
node_gui -.->|"evaluates map"| node_map_eval

click node_gui "https://github.com/damaf77/codebase-assistant/blob/main/app/main.py"
click node_indexer "https://github.com/damaf77/codebase-assistant/blob/main/app/services/indexer.py"
click node_database "https://github.com/damaf77/codebase-assistant/blob/main/app/services/databases.py"
click node_retrieval "https://github.com/damaf77/codebase-assistant/blob/main/app/services/databases.py"
click node_retrieval_eval "https://github.com/damaf77/codebase-assistant/blob/main/app/services/evaluation.py"
click node_insights "https://github.com/damaf77/codebase-assistant/blob/main/app/services/project_insights.py"
click node_maintenance "https://github.com/damaf77/codebase-assistant/blob/main/app/services/maintenance_analysis.py"
click node_impact "https://github.com/damaf77/codebase-assistant/blob/main/app/services/maintenance_analysis.py"
click node_ai_service "https://github.com/damaf77/codebase-assistant/blob/main/app/services/ai_provider.py"
click node_provider_common "https://github.com/damaf77/codebase-assistant/blob/main/app/providers/common.py"
click node_gemini "https://github.com/damaf77/codebase-assistant/blob/main/app/providers/gemini.py"
click node_groq "https://github.com/damaf77/codebase-assistant/blob/main/app/providers/groq.py"
click node_openai "https://github.com/damaf77/codebase-assistant/blob/main/app/providers/openai.py"
click node_openrouter "https://github.com/damaf77/codebase-assistant/blob/main/app/providers/openrouter.py"
click node_repo_map "https://github.com/damaf77/codebase-assistant/blob/main/app/services/repository_map.py"
click node_map_eval "https://github.com/damaf77/codebase-assistant/blob/main/app/services/repository_map_evaluation.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_gui,node_user toneBlue
class node_indexer,node_database,node_retrieval,node_retrieval_eval toneAmber
class node_insights,node_maintenance,node_impact toneMint
class node_ai_service,node_provider_common,node_gemini,node_groq,node_openai,node_openrouter,node_providers toneRose
class node_repo_map,node_map_eval toneIndigo
```

## Components

### Desktop workflow

- [Desktop GUI](https://github.com/damaf77/codebase-assistant/blob/main/app/main.py): `app/main.py`

### Local indexing and search

- [Python indexer](https://github.com/damaf77/codebase-assistant/blob/main/app/services/indexer.py): `app/services/indexer.py`
- [SQLite code index](https://github.com/damaf77/codebase-assistant/blob/main/app/services/databases.py): `app/services/databases.py`
- [Code retrieval](https://github.com/damaf77/codebase-assistant/blob/main/app/services/databases.py): `app/services/databases.py`
- [Retrieval evaluation](https://github.com/damaf77/codebase-assistant/blob/main/app/services/evaluation.py): `app/services/evaluation.py`

### Project analysis

- [Project insights](https://github.com/damaf77/codebase-assistant/blob/main/app/services/project_insights.py): `app/services/project_insights.py`
- [Maintenance analysis](https://github.com/damaf77/codebase-assistant/blob/main/app/services/maintenance_analysis.py): `app/services/maintenance_analysis.py`
- [Import impact](https://github.com/damaf77/codebase-assistant/blob/main/app/services/maintenance_analysis.py): `app/services/maintenance_analysis.py`

### AI assistance

- [AI orchestration](https://github.com/damaf77/codebase-assistant/blob/main/app/services/ai_provider.py): `app/services/ai_provider.py`
- [Provider HTTP](https://github.com/damaf77/codebase-assistant/blob/main/app/providers/common.py): `app/providers/common.py`
- [Gemini adapter](https://github.com/damaf77/codebase-assistant/blob/main/app/providers/gemini.py): `app/providers/gemini.py`
- [Groq adapter](https://github.com/damaf77/codebase-assistant/blob/main/app/providers/groq.py): `app/providers/groq.py`
- [OpenAI adapter](https://github.com/damaf77/codebase-assistant/blob/main/app/providers/openai.py): `app/providers/openai.py`
- [OpenRouter adapter](https://github.com/damaf77/codebase-assistant/blob/main/app/providers/openrouter.py): `app/providers/openrouter.py`
- **AI providers**

### Repository mapping

- [Repository map](https://github.com/damaf77/codebase-assistant/blob/main/app/services/repository_map.py): `app/services/repository_map.py`
- [Map evaluation](https://github.com/damaf77/codebase-assistant/blob/main/app/services/repository_map_evaluation.py): `app/services/repository_map_evaluation.py`

### Other components

- **Project user**

## Connections

- Project user → Desktop GUI: selects project (evidence: `README.md`)
- Desktop GUI → Python indexer: indexes project (evidence: `app/main.py`)
- Desktop GUI → SQLite code index: saves chunks (evidence: `app/main.py`)
- Desktop GUI → Maintenance analysis: runs checks (evidence: `app/main.py`)
- Desktop GUI → Repository map: builds map (evidence: `app/main.py`)
- Desktop GUI → Code retrieval: searches index (evidence: `README.md`)
- Code retrieval → SQLite code index: queries chunks (evidence: `app/services/databases.py`)
- Desktop GUI → Project insights: requests insights (evidence: `README.md`)
- Desktop GUI → Import impact: requests impact (evidence: `README.md`)
- Maintenance analysis → Import impact: provides import graph (evidence: `app/services/maintenance_analysis.py`)
- Desktop GUI → AI orchestration: asks repository (evidence: `README.md`)
- AI orchestration → Code retrieval: retrieves context (evidence: `README.md`)
- AI orchestration → Gemini adapter: dispatches to (evidence: `app/services/ai_provider.py`)
- AI orchestration → Groq adapter: dispatches to (evidence: `app/services/ai_provider.py`)
- AI orchestration → OpenAI adapter: dispatches to (evidence: `app/services/ai_provider.py`)
- AI orchestration → OpenRouter adapter: dispatches to (evidence: `app/services/ai_provider.py`)
- Gemini adapter → Provider HTTP: posts request (evidence: `app/providers/gemini.py`)
- OpenAI adapter → Provider HTTP: posts request (evidence: `app/providers/openai.py`)
- OpenRouter adapter → Provider HTTP: posts request (evidence: `app/providers/openrouter.py`)
- Provider HTTP → AI providers: sends HTTP (evidence: `app/providers/common.py`)
- Desktop GUI → Retrieval evaluation: evaluates retrieval
- Desktop GUI → Map evaluation: evaluates map
