# utkarshshukla1180/github-repository-copilot architecture

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

- Interactive diagram: https://gitdiagram.com/utkarshshukla1180/github-repository-copilot
- Repository: https://github.com/utkarshshukla1180/github-repository-copilot

## Overview

Repository Copilot lets a user add a public Python repository, index its code, and ask questions answered from retrieved source. The documented flow clones and AST-chunks files, embeds and stores chunks, then rewrites questions, combines semantic and keyword retrieval, expands dependencies, and generates a grounded answer. The graph preserves the documented frontend, authentication, persistence, and AI-service capabilities. Some indexing and UI wiring is documented rather than shown in excerpts; those edges cite the README.

Main entry points: [`backend.py`](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/backend.py) (Index and answer orchestration), [`repository-copilot-frontend/src/App.tsx`](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/App.tsx) (App and screens), [`app.py`](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/app.py) (HTTP orchestration), [`retrieval/hybrid.py`](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/hybrid.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web client"]
  node_frontend["App and screens<br/>[App.tsx]"]
  node_client_api["API client<br/>[api.ts]"]
  node_chat_ui["Chat interface<br/>[ChatWindow.tsx]"]
  node_chat_hook["Chat state<br/>[useChat.ts]"]
  node_repo_hook["Repository indexing UI"]
  node_sessions["Session history<br/>[useSessions.ts]"]
end

subgraph group_api["API and accounts"]
  node_auth["Token verification<br/>[auth.py]"]
  node_api_routes["HTTP orchestration<br/>[app.py]"]
  node_sql_crud["Account and chat data<br/>[crud.py]"]
  node_sql_models["Persistence schema<br/>[models.py]"]
end

subgraph group_indexing["Repository indexing"]
  node_clone["Repository clone<br/>[clone_repo.py]"]
  node_read_files["Source file loading<br/>[read_files.py]"]
  node_chunker["AST chunking<br/>[chunker.py]"]
  node_embeddings["Embedding generation<br/>[embeddings.py]"]
  node_chunk_store["Chunk and BM25 store<br/>[chunk_store.py]"]
  node_vector_store["Collection management<br/>[vector_store.py]"]
end

subgraph group_qa["Question answering"]
  node_index_orchestrator["Index and answer orchestration<br/>[backend.py]"]
  node_retrieval["Hybrid retrieval<br/>[hybrid.py]"]
  node_semantic["Semantic search<br/>[retrieve.py]"]
  node_keyword["Keyword search<br/>[keyword_search.py]"]
  node_fusion["Rank fusion<br/>[rrf.py]"]
  node_dependency["Dependency expansion<br/>[dependency.py]"]
  node_rewrite["Question rewriting<br/>[rewrite.py]"]
  node_generation["Answer generation<br/>[generate.py]"]
  node_provider["Model provider<br/>[provider.py]"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]
node_qdrant[("Qdrant")]
node_gemini{{"Gemini API"}}
node_ollama{{"Ollama"}}
node_supabase{{"Supabase Auth"}}

node_user -->|"uses"| node_frontend
node_frontend -.->|"requests"| node_client_api
node_frontend -.->|"renders"| node_chat_ui
node_frontend -.->|"uses"| node_chat_hook
node_frontend -.->|"uses"| node_repo_hook
node_frontend -.->|"loads"| node_sessions
node_client_api -.->|"calls"| node_api_routes
node_api_routes -->|"checks tokens"| node_auth
node_auth -->|"verifies token"| node_supabase
node_api_routes -->|"starts indexing and asks"| node_index_orchestrator
node_api_routes -->|"reads and writes"| node_sql_crud
node_sql_crud -->|"uses models"| node_sql_models
node_sql_models -.->|"persists records"| node_postgres
node_index_orchestrator -->|"clones repository"| node_clone
node_index_orchestrator -->|"loads source"| node_read_files
node_index_orchestrator -->|"chunks code"| node_chunker
node_index_orchestrator -->|"embeds chunks"| node_embeddings
node_index_orchestrator -->|"stores chunks"| node_chunk_store
node_index_orchestrator -->|"manages collection"| node_vector_store
node_chunk_store -->|"uses client"| node_vector_store
node_vector_store -->|"stores vectors"| node_qdrant
node_embeddings -->|"requests embeddings"| node_gemini
node_index_orchestrator -->|"rewrites question"| node_rewrite
node_index_orchestrator -->|"retrieves chunks"| node_retrieval
node_retrieval -->|"runs semantic search"| node_semantic
node_retrieval -->|"runs keyword search"| node_keyword
node_retrieval -->|"merges rankings"| node_fusion
node_semantic -->|"embeds query"| node_embeddings
node_semantic -->|"queries collection"| node_vector_store
node_keyword -->|"gets BM25 index"| node_chunk_store
node_index_orchestrator -->|"expands references"| node_dependency
node_dependency -->|"searches referenced code"| node_keyword
node_index_orchestrator -->|"generates grounded answer"| node_generation
node_rewrite -->|"uses completion"| node_generation
node_generation -->|"delegates completion"| node_provider
node_provider -.->|"calls when configured"| node_gemini
node_provider -.->|"calls when configured"| node_ollama

click node_frontend "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/App.tsx"
click node_client_api "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/services/api.ts"
click node_chat_ui "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/components/ChatWindow/ChatWindow.tsx"
click node_chat_hook "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/hooks/useChat.ts"
click node_repo_hook "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/hooks/useCloneRepository.ts"
click node_sessions "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/hooks/useSessions.ts"
click node_auth "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/auth.py"
click node_api_routes "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/app.py"
click node_sql_crud "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/database/crud.py"
click node_sql_models "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/database/models.py"
click node_index_orchestrator "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/backend.py"
click node_clone "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/clone_repo.py"
click node_read_files "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/read_files.py"
click node_chunker "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/chunker.py"
click node_embeddings "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/embeddings.py"
click node_chunk_store "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/chunk_store.py"
click node_vector_store "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/vector_store.py"
click node_retrieval "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/hybrid.py"
click node_semantic "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/retrieve.py"
click node_keyword "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/keyword_search.py"
click node_fusion "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/rrf.py"
click node_dependency "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/dependency.py"
click node_rewrite "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/llm/rewrite.py"
click node_generation "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/llm/generate.py"
click node_provider "https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/llm/provider.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_frontend,node_client_api,node_chat_ui,node_chat_hook,node_repo_hook,node_sessions,node_user toneBlue
class node_auth,node_api_routes,node_sql_crud,node_sql_models,node_postgres,node_qdrant toneAmber
class node_clone,node_read_files,node_chunker,node_embeddings,node_chunk_store,node_vector_store,node_gemini toneMint
class node_index_orchestrator,node_retrieval,node_semantic,node_keyword,node_fusion,node_dependency,node_rewrite,node_generation,node_provider toneRose
class node_ollama,node_supabase toneIndigo
```

## Components

### Web client

- [App and screens](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/App.tsx): `repository-copilot-frontend/src/App.tsx`
- [API client](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/services/api.ts): `repository-copilot-frontend/src/services/api.ts`
- [Chat interface](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/components/ChatWindow/ChatWindow.tsx): `repository-copilot-frontend/src/components/ChatWindow/ChatWindow.tsx`
- [Chat state](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/hooks/useChat.ts): `repository-copilot-frontend/src/hooks/useChat.ts`
- [Repository indexing UI](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/hooks/useCloneRepository.ts): `repository-copilot-frontend/src/hooks/useCloneRepository.ts`
- [Session history](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/repository-copilot-frontend/src/hooks/useSessions.ts): `repository-copilot-frontend/src/hooks/useSessions.ts`

### API and accounts

- [Token verification](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/auth.py): `auth.py`
- [HTTP orchestration](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/app.py): `app.py`
- [Account and chat data](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/database/crud.py): `database/crud.py`
- [Persistence schema](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/database/models.py): `database/models.py`

### Repository indexing

- [Repository clone](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/clone_repo.py): `clone_repo.py`
- [Source file loading](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/read_files.py): `read_files.py`
- [AST chunking](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/chunker.py): `chunker.py`
- [Embedding generation](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/embeddings.py): `embeddings.py`
- [Chunk and BM25 store](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/chunk_store.py): `chunk_store.py`
- [Collection management](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/vector_store.py): `vector_store.py`

### Question answering

- [Index and answer orchestration](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/backend.py): `backend.py`
- [Hybrid retrieval](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/hybrid.py): `retrieval/hybrid.py`
- [Semantic search](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/retrieve.py): `retrieval/retrieve.py`
- [Keyword search](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/keyword_search.py): `retrieval/keyword_search.py`
- [Rank fusion](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/rrf.py): `retrieval/rrf.py`
- [Dependency expansion](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/retrieval/dependency.py): `retrieval/dependency.py`
- [Question rewriting](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/llm/rewrite.py): `llm/rewrite.py`
- [Answer generation](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/llm/generate.py): `llm/generate.py`
- [Model provider](https://github.com/utkarshshukla1180/github-repository-copilot/blob/main/llm/provider.py): `llm/provider.py`

### Other components

- **User**
- **PostgreSQL**
- **Qdrant**
- **Gemini API**
- **Ollama**
- **Supabase Auth**

## Connections

- User → App and screens: uses (evidence: `README.md`)
- App and screens → API client: requests
- App and screens → Chat interface: renders
- App and screens → Chat state: uses
- App and screens → Repository indexing UI: uses
- App and screens → Session history: loads
- API client → HTTP orchestration: calls (evidence: `README.md`)
- HTTP orchestration → Token verification: checks tokens (evidence: `app.py`)
- Token verification → Supabase Auth: verifies token (evidence: `auth.py`)
- HTTP orchestration → Index and answer orchestration: starts indexing and asks (evidence: `app.py`)
- HTTP orchestration → Account and chat data: reads and writes (evidence: `app.py`)
- Account and chat data → Persistence schema: uses models (evidence: `database/crud.py`)
- Persistence schema → PostgreSQL: persists records (evidence: `README.md`)
- Index and answer orchestration → Repository clone: clones repository (evidence: `backend.py`)
- Index and answer orchestration → Source file loading: loads source (evidence: `backend.py`)
- Index and answer orchestration → AST chunking: chunks code (evidence: `backend.py`)
- Index and answer orchestration → Embedding generation: embeds chunks (evidence: `backend.py`)
- Index and answer orchestration → Chunk and BM25 store: stores chunks (evidence: `backend.py`)
- Index and answer orchestration → Collection management: manages collection (evidence: `backend.py`)
- Chunk and BM25 store → Collection management: uses client (evidence: `chunk_store.py`)
- Collection management → Qdrant: stores vectors (evidence: `README.md`)
- Embedding generation → Gemini API: requests embeddings (evidence: `embeddings.py`)
- Index and answer orchestration → Question rewriting: rewrites question (evidence: `backend.py`)
- Index and answer orchestration → Hybrid retrieval: retrieves chunks (evidence: `backend.py`)
- Hybrid retrieval → Semantic search: runs semantic search (evidence: `retrieval/hybrid.py`)
- Hybrid retrieval → Keyword search: runs keyword search (evidence: `retrieval/hybrid.py`)
- Hybrid retrieval → Rank fusion: merges rankings (evidence: `retrieval/hybrid.py`)
- Semantic search → Embedding generation: embeds query (evidence: `retrieval/retrieve.py`)
- Semantic search → Collection management: queries collection (evidence: `retrieval/retrieve.py`)
- Keyword search → Chunk and BM25 store: gets BM25 index (evidence: `retrieval/keyword_search.py`)
- Index and answer orchestration → Dependency expansion: expands references (evidence: `backend.py`)
- Dependency expansion → Keyword search: searches referenced code (evidence: `retrieval/dependency.py`)
- Index and answer orchestration → Answer generation: generates grounded answer (evidence: `backend.py`)
- Question rewriting → Answer generation: uses completion (evidence: `llm/rewrite.py`)
- Answer generation → Model provider: delegates completion (evidence: `llm/generate.py`)
- Model provider → Gemini API: calls when configured (evidence: `llm/provider.py`)
- Model provider → Ollama: calls when configured (evidence: `llm/provider.py`)
