# hsk-2004/codemind architecture

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

- Interactive diagram: https://gitdiagram.com/hsk-2004/codemind
- Repository: https://github.com/hsk-2004/codemind

## Overview

CodeMind is a local-first AI codebase assistant. A user connects a GitHub repository, previews and indexes its files, then explores summaries, semantic search, and code-grounded questions; the dashboard also surfaces commit summaries and breaking-change analysis. The app exposes these workflows through Next.js pages and tRPC, with PostgreSQL/pgvector for project data and retrieval, local Ollama models by default, and optional cloud chat models. The README documents several flows; unsampled implementations and some UI-to-router wiring are represented only where documented, not inferred.

Main entry points: [`src/server/api/routers/project.ts`](https://github.com/hsk-2004/codemind/blob/main/src/server/api/routers/project.ts) (Project API), [`src/lib/github-loader.ts`](https://github.com/hsk-2004/codemind/blob/main/src/lib/github-loader.ts) (Repository indexing), [`src/services/rag/retriever.ts`](https://github.com/hsk-2004/codemind/blob/main/src/services/rag/retriever.ts) (Vector retrieval), [`src/services/llm`](https://github.com/hsk-2004/codemind/tree/main/src/services/llm) (LLM providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_workspace["Workspace pages"]
  node_connect["Connect repository<br/>[page.tsx]"]
  node_ask["Ask AI"]
  node_search["Semantic search<br/>[page.tsx]"]
  node_files["Repository files<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_metrics["AI metrics<br/>[page.tsx]"]
  node_status["System status<br/>[page.tsx]"]
end

subgraph group_project["Repository workflows"]
  node_indexing["Repository indexing<br/>[github-loader.ts]"]
  node_commit["Commit analysis<br/>[github.ts]"]
  node_insights["Repository insights<br/>[repo-insights.ts]"]
end

subgraph group_ai["AI services"]
  node_rag["RAG and direct QA<br/>[chain.ts]"]
  node_retriever["Vector retrieval<br/>[retriever.ts]"]
  node_excerpt["Context excerpts<br/>[excerpt.ts]"]
  node_embeddings["Embedding provider<br/>[index.ts]"]
  node_llm["LLM providers"]
end

subgraph group_platform["Server platform"]
  node_projectapi["Project API<br/>[project.ts]"]
  node_trpc["tRPC API<br/>[trpc.ts]"]
end

subgraph group_integrations["Stores and providers"]
  node_db[("PostgreSQL pgvector<br/>[db.ts]")]
  node_github["GitHub API"]
  node_ollama["Ollama"]
  node_cloud["Gemini / Groq"]
  node_qdrant[("Qdrant<br/>[qdrant.ts]")]
end

node_developer(("Developer"))

node_developer -->|"uses"| node_workspace
node_developer -->|"connects repository"| node_connect
node_developer -->|"asks questions"| node_ask
node_workspace -.->|"uses tRPC"| node_projectapi
node_connect -.->|"starts indexing"| node_projectapi
node_projectapi -->|"loads and indexes"| node_indexing
node_projectapi -->|"requests commit work"| node_commit
node_projectapi -->|"requests insights"| node_insights
node_indexing -->|"loads repository"| node_github
node_indexing -->|"summarizes files"| node_llm
node_indexing -->|"embeds summaries"| node_embeddings
node_indexing -->|"stores vectors"| node_db
node_commit -->|"polls commits"| node_github
node_commit -->|"summarizes and classifies"| node_llm
node_ask -->|"submits question"| node_rag
node_search -.->|"searches embeddings"| node_retriever
node_rag -->|"retrieves sources"| node_retriever
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"queries vectors"| node_db
node_retriever -->|"selects excerpts"| node_excerpt
node_rag -->|"generates answer"| node_llm
node_llm -->|"runs locally"| node_ollama
node_llm -.->|"routes optionally"| node_cloud
node_files -.->|"loads indexed files"| node_projectapi
node_dashboard -.->|"loads project data"| node_projectapi
node_metrics -.->|"requests metrics"| node_trpc
node_status -->|"requests health"| node_trpc
node_trpc -->|"uses database"| node_db
node_status -->|"reports provisioned status"| node_qdrant

click node_workspace "https://github.com/hsk-2004/codemind/tree/main/src/app/(workspace)"
click node_connect "https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/create/page.tsx"
click node_ask "https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/dashboard/ask-question-card.tsx"
click node_search "https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/search/page.tsx"
click node_files "https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/files/page.tsx"
click node_dashboard "https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/dashboard/page.tsx"
click node_metrics "https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/metrics/page.tsx"
click node_status "https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/system/page.tsx"
click node_projectapi "https://github.com/hsk-2004/codemind/blob/main/src/server/api/routers/project.ts"
click node_indexing "https://github.com/hsk-2004/codemind/blob/main/src/lib/github-loader.ts"
click node_commit "https://github.com/hsk-2004/codemind/blob/main/src/lib/github.ts"
click node_insights "https://github.com/hsk-2004/codemind/blob/main/src/lib/repo-insights.ts"
click node_rag "https://github.com/hsk-2004/codemind/blob/main/src/services/rag/chain.ts"
click node_retriever "https://github.com/hsk-2004/codemind/blob/main/src/services/rag/retriever.ts"
click node_excerpt "https://github.com/hsk-2004/codemind/blob/main/src/services/rag/excerpt.ts"
click node_embeddings "https://github.com/hsk-2004/codemind/blob/main/src/services/embedding/index.ts"
click node_llm "https://github.com/hsk-2004/codemind/tree/main/src/services/llm"
click node_trpc "https://github.com/hsk-2004/codemind/blob/main/src/server/api/trpc.ts"
click node_db "https://github.com/hsk-2004/codemind/blob/main/src/server/db.ts"
click node_qdrant "https://github.com/hsk-2004/codemind/blob/main/src/services/vectorstore/qdrant.ts"

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_workspace,node_connect,node_ask,node_search,node_files,node_dashboard,node_metrics,node_status toneBlue
class node_indexing,node_commit,node_insights toneAmber
class node_rag,node_retriever,node_excerpt,node_embeddings,node_llm toneMint
class node_projectapi,node_trpc toneRose
class node_db,node_github,node_ollama,node_cloud,node_qdrant,node_developer toneIndigo
```

## Components

### App experience

- [Workspace pages](https://github.com/hsk-2004/codemind/tree/main/src/app/(workspace)): `src/app/(workspace)`
- [Connect repository](https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/create/page.tsx): `src/app/(workspace)/create/page.tsx`
- [Ask AI](https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/dashboard/ask-question-card.tsx): `src/app/(workspace)/dashboard/ask-question-card.tsx`
- [Semantic search](https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/search/page.tsx): `src/app/(workspace)/search/page.tsx`
- [Repository files](https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/files/page.tsx): `src/app/(workspace)/files/page.tsx`
- [Dashboard](https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/dashboard/page.tsx): `src/app/(workspace)/dashboard/page.tsx`
- [AI metrics](https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/metrics/page.tsx): `src/app/(workspace)/metrics/page.tsx`
- [System status](https://github.com/hsk-2004/codemind/blob/main/src/app/(workspace)/system/page.tsx): `src/app/(workspace)/system/page.tsx`

### Repository workflows

- [Repository indexing](https://github.com/hsk-2004/codemind/blob/main/src/lib/github-loader.ts): `src/lib/github-loader.ts`
- [Commit analysis](https://github.com/hsk-2004/codemind/blob/main/src/lib/github.ts): `src/lib/github.ts`
- [Repository insights](https://github.com/hsk-2004/codemind/blob/main/src/lib/repo-insights.ts): `src/lib/repo-insights.ts`

### AI services

- [RAG and direct QA](https://github.com/hsk-2004/codemind/blob/main/src/services/rag/chain.ts): `src/services/rag/chain.ts`
- [Vector retrieval](https://github.com/hsk-2004/codemind/blob/main/src/services/rag/retriever.ts): `src/services/rag/retriever.ts`
- [Context excerpts](https://github.com/hsk-2004/codemind/blob/main/src/services/rag/excerpt.ts): `src/services/rag/excerpt.ts`
- [Embedding provider](https://github.com/hsk-2004/codemind/blob/main/src/services/embedding/index.ts): `src/services/embedding/index.ts`
- [LLM providers](https://github.com/hsk-2004/codemind/tree/main/src/services/llm): `src/services/llm`

### Server platform

- [Project API](https://github.com/hsk-2004/codemind/blob/main/src/server/api/routers/project.ts): `src/server/api/routers/project.ts`
- [tRPC API](https://github.com/hsk-2004/codemind/blob/main/src/server/api/trpc.ts): `src/server/api/trpc.ts`

### Stores and providers

- [PostgreSQL pgvector](https://github.com/hsk-2004/codemind/blob/main/src/server/db.ts): `src/server/db.ts`
- **GitHub API**
- **Ollama**
- **Gemini / Groq**
- [Qdrant](https://github.com/hsk-2004/codemind/blob/main/src/services/vectorstore/qdrant.ts): `src/services/vectorstore/qdrant.ts`

### Other components

- **Developer**

## Connections

- Developer → Workspace pages: uses (evidence: `README.md`)
- Developer → Connect repository: connects repository (evidence: `README.md`)
- Developer → Ask AI: asks questions (evidence: `README.md`)
- Workspace pages → Project API: uses tRPC
- Connect repository → Project API: starts indexing
- Project API → Repository indexing: loads and indexes (evidence: `src/server/api/routers/project.ts`)
- Project API → Commit analysis: requests commit work (evidence: `src/server/api/routers/project.ts`)
- Project API → Repository insights: requests insights (evidence: `src/server/api/routers/project.ts`)
- Repository indexing → GitHub API: loads repository (evidence: `README.md`)
- Repository indexing → LLM providers: summarizes files (evidence: `README.md`)
- Repository indexing → Embedding provider: embeds summaries (evidence: `README.md`)
- Repository indexing → PostgreSQL pgvector: stores vectors (evidence: `README.md`)
- Commit analysis → GitHub API: polls commits (evidence: `README.md`)
- Commit analysis → LLM providers: summarizes and classifies (evidence: `README.md`)
- Ask AI → RAG and direct QA: submits question (evidence: `README.md`)
- Semantic search → Vector retrieval: searches embeddings
- RAG and direct QA → Vector retrieval: retrieves sources (evidence: `README.md`)
- Vector retrieval → Embedding provider: embeds query (evidence: `README.md`)
- Vector retrieval → PostgreSQL pgvector: queries vectors (evidence: `README.md`)
- Vector retrieval → Context excerpts: selects excerpts (evidence: `README.md`)
- RAG and direct QA → LLM providers: generates answer (evidence: `README.md`)
- LLM providers → Ollama: runs locally (evidence: `README.md`)
- LLM providers → Gemini / Groq: routes optionally (evidence: `README.md`)
- Repository files → Project API: loads indexed files
- Dashboard → Project API: loads project data
- AI metrics → tRPC API: requests metrics
- System status → tRPC API: requests health (evidence: `src/app/(workspace)/system/page.tsx`)
- tRPC API → PostgreSQL pgvector: uses database (evidence: `src/server/api/trpc.ts`)
- System status → Qdrant: reports provisioned status
