# floaredor/gitask architecture

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

- Interactive diagram: https://gitdiagram.com/floaredor/gitask
- Repository: https://github.com/floaredor/gitask

## Overview

GitAsk is a browser-first repository Q&A system built as a Next.js app, but most of the real architecture lives on the client side. The key architectural boundary is:

- Browser runtime: indexing, retrieval, local model inference, and persistence
- Optional cloud boundary: Gemini/Groq BYOK paths
- External source boundary: GitHub repo contents

#### 1) Main system shape

The app is organized around a single repo workspace experience:

- A user pastes a GitHub repo URL
- The app fetches the repository tree and file contents
- The repo is indexed locally in the browser
- The user asks questions in a chat UI
- Retrieval gathers relevant code context
- A local or optional cloud LLM generates the answer
- Answers are grounded with citations and a verification pass

This is not a server-centric RAG system. The durable state is stored locally in the browser, primarily in IndexedDB.

#### 2) Frontend and route structure

The Next.js App Router provides the UI shell and route-level entry points:

- `src/app/page.tsx`: landing / repo entry point
- `src/app/[owner]/[repo]/page.tsx`: the main repo chat workspace
- `src/app/storage/page.tsx`: local storage / index inspection
- `src/app/metrics/page.tsx`: metrics and evaluation views
- `src/app/ablation/page.tsx`: experimental / ablation views

Supporting UI is split into components for:

- chat experience: input, messages, sidebar, file browser, context drawer, repo header
- repo/index browsing: index browser, indexing progress, AST tree view
- diagrams: architecture diagram rendering and modal/inline display
- settings and UX: model settings, theme toggle, token input

This suggests the product has a primary “talk to a repo” path, plus observability and experiment pages for inspecting how the retrieval pipeline behaves.

#### 3) Repository ingestion pipeline

The ingestion pipeline is the first major subsystem.

##### Source acquisition
`src/lib/github.ts` is responsible for interacting with GitHub. The README says the app pulls the full file tree in one API call and then fetches file contents on demand. That means the app needs:

- repo metadata and directory tree discovery
- lazy file fetching for actual content ingestion

##### Parsing and chunking
Code is split using AST-aware chunking instead of naive line slicing:

- Tree-sitter WASM grammars live in `public/wasms`
- `src/lib/chunker.ts` and related tests handle chunk formation
- `src/lib/directorySummary.ts` likely generates higher-level directory context
- `src/lib/graph.ts` and `src/lib/graphExpansion.ts` build and use dependency/definition relationships

This is an important architectural boundary because the system preserves code structure when turning source into retrieval units. The supported languages listed in the README match the shipped Tree-sitter grammars: JS/TS/TSX, Python, Rust, Go, Java, C/C++, and fallback text splitting for the rest.

##### Embedding and compression
`src/lib/embedder.ts` uses `@huggingface/transformers` and runs embeddings in-browser. The runtime can use:

- WebGPU when available
- WASM fallback when WebGPU is unavailable

The embedding model is `all-MiniLM-L12-v2`. After embedding:

- `src/lib/quantize.ts` binary-quantizes vectors into packed bit representations
- this reduces memory use significantly and speeds approximate similarity work

##### Persistence
`src/lib/vectorStore.ts` and the README point to IndexedDB persistence via `@babycommando/entity-db`.

So the ingestion output is a browser-local repository index containing:

- chunk text
- AST-aware metadata
- dense embeddings
- quantized vectors
- sparse/BM25 data
- graph relations
- repo/session state

This local persistence is central: closing the tab does not destroy the index.

#### 4) Retrieval subsystem

Retrieval is more than plain vector search; it is a multi-stage pipeline.

##### Query processing
The query side includes:

- `src/lib/queryUtils.ts`
- `src/lib/queryExpansion.ts`
- `src/lib/promptSafety.ts`
- `src/lib/chatUtils.ts`

The README describes:
- multi-query expansion
- follow-up query enrichment from prior chat turns
- adaptive retrieval refinement if the first pass is weak

That means a user question is not sent directly to one retrieval pass. It is transformed based on conversation context and rerun when needed.

##### Hybrid search
The search layer combines:

- dense retrieval: `src/lib/search.ts`, `src/lib/vectorStore.ts`, `src/lib/quantize.ts`
- sparse retrieval: `src/lib/bm25.ts`, `src/lib/bm25-core.ts`
- fusion: reciprocal rank fusion is implied by the README and likely implemented across search utilities

This hybrid design matters architecturally because the system does not depend on one similarity signal. Code search works better when lexical matches and semantic matches are combined.

##### Graph expansion
`src/lib/graph.ts` and `src/lib/graphExpansion.ts` add a dependency-aware retrieval hop. This is used when chunk boundaries miss adjacent but necessary context, such as:

- imports
- definitions
- call relationships

So retrieval is not just “top-k chunks”; it can expand across the repository graph.

##### Reranking and context assembly
After candidate retrieval, the pipeline performs reranking and assembly:

- `src/lib/contextAssembly.ts` builds the final prompt context
- `src/lib/citationUtils.ts` supports answer grounding
- `src/lib/cove.ts` is used for verification-oriented generation behavior

The README mentions a cosine rerank after coarse RRF candidates. Architecturally, this is the handoff point from retrieval to generation.

#### 5) Generation subsystem

Generation is pluggable, but the default architecture is local-first.

##### Local model path
`src/lib/llm.ts` and `src/workers/llm-worker.ts` handle LLM execution. The README says the default model is Qwen2-0.5B via `@mlc-ai/web-llm`, running fully in the browser.

This introduces an important runtime boundary:

- model inference happens in the browser
- WebGPU is used when possible
- the model is cached locally after download

##### Optional BYOK cloud path
There are optional routes and vault modules for cloud providers:

- `src/app/api/gemini/route.ts`
- `src/app/api/groq/route.ts`
- `src/lib/gemini-vault.ts`
- `src/lib/groq-vault.ts`

The README describes BYOK support with encrypted local storage for keys. So the cloud provider path is an opt-in alternate generation boundary, not the core dependency of the system.

##### CoVe verification loop
`src/lib/cove.ts` implements the chain-of-verification style post-processing described in the README:

1. generate answer
2. extract claims
3. check claims against the repo index / vector store
4. revise incorrect or unsupported claims

This is a separate generation-time quality gate layered on top of the LLM.

#### 6) Chat and session management

The app is chat-centric, and the chat layer is its own subsystem:

- `src/lib/chatHistory.ts` stores and retrieves conversation state
- `src/components/chat/*` contains the interactive UI
- `src/components/ModelSettings.tsx` exposes model/provider controls
- `src/components/chat/TokenInput.tsx` suggests user-configurable provider tokens or settings

The README notes multi-session chat per repo. Architecturally, this means the system maintains:

- repo-scoped conversation histories
- persistent local sessions
- a current active conversation context that feeds query expansion

#### 7) Visualization and inspection tools

There is a substantial set of inspection components and pages, which are useful when drawing the architecture diagram because they reflect internal subsystems:

- AST structure visualization: `AstTreeView.tsx`
- repository browsing: `IndexBrowser.tsx`, `FileBrowser.tsx`
- indexing progress overlays: `IndexingProgress.tsx`, `IndexingOverlay.tsx`
- architecture diagram rendering: `ArchitectureDiagram.tsx`, `diagram/*`
- repo cards and repo headers for navigation context

These are not core data-path components, but they expose internal state to the user, which is a strong hint that the app is designed to make the indexing/retrieval pipeline inspectable.

#### 8) Workers and execution boundaries

Heavy work is split into workers:

- `src/workers/embed-worker.ts`
- `src/workers/llm-worker.ts`
- `src/workers/bm25-worker.ts`

That means the architecture is not a single monolithic UI thread. The browser app offloads:

- embeddings
- LLM inference orchestration
- lexical indexing/search

This separation is important for responsiveness and for keeping the UI usable while the repo is being indexed or the model is loading.

#### 9) Supporting libraries and internal boundaries

Several libraries define the internal pipeline stages:

- `indexer.ts`: orchestration of repo ingestion and index build
- `search.ts`: retrieval orchestration
- `contextAssembly.ts`: prompt context building
- `promptSafety.ts`: input/output guardrails
- `citationUtils.ts`: citation and provenance support
- `pageIndexSearch.ts` / `pageIndexTree.ts`: page-level lookup or tree views
- `metrics.ts`, `eval-data.ts`, `eval-results.ts`: measurement and evaluation plumbing
- `queryExpansion.ts`, `graphExpansion.ts`: retrieval enhancement logic

These files show a layered architecture:

1. source ingestion
2. chunking and enrichment
3. indexing
4. retrieval
5. context assembly
6. generation
7. verification
8. presentation

#### 10) Evaluation and experiments

The repo includes a non-user-facing evaluation and benchmarking toolchain:

- `scripts/generate_eval_repo.py`
- `scripts/generate_eval_codesearchnet.py`
- `scripts/precompute-eval-embeddings.*`
- `scripts/test-*.js`
- `src/lib/*test.ts`
- CI workflow in `.github/workflows/ci.yml`

This implies the project is actively benchmarked around retrieval quality, model/provider behavior, and pipeline correctness. It is not just a UI demo; it has an internal evaluation loop for retrieval and generation behavior.

#### 11) The most important diagram boundaries

If you are drawing the architecture, the main boxes should be:

- User/browser UI
- Repo ingestion from GitHub
- Local parsing/chunking/graph building
- Local embedding + quantization
- Local persistence in IndexedDB
- Hybrid retrieval engine
- Local LLM inference via WebLLM
- Optional Gemini/Groq BYOK path
- Verification / CoVe loop
- Inspection and metrics tools

And the most important data flows are:

1. GitHub repo URL -> fetch tree/files -> AST chunking -> embeddings -> IndexedDB
2. User question + chat history -> query expansion -> hybrid retrieval -> graph expansion -> rerank -> context assembly
3. Context -> local/optional LLM -> answer
4. Answer -> verification against local index -> corrected final response
5. All repo state and session state remain in-browser

Overall, GitAsk is best understood as a fully client-side RAG pipeline embedded in a Next.js shell, with optional cloud model adapters and a strong emphasis on local persistence, code-aware chunking, and retrieval quality.

Main entry points: [`src/components/chat`](https://github.com/floaredor/gitask/tree/HEAD/src/components/chat) (Chat UI), [`src/lib/chunker.ts`](https://github.com/floaredor/gitask/blob/HEAD/src/lib/chunker.ts) (Chunking), [`src/lib/vectorStore.ts`](https://github.com/floaredor/gitask/blob/HEAD/src/lib/vectorStore.ts) (IndexedDB store), [`src/app/[owner]/[repo]/page.tsx`](https://github.com/floaredor/gitask/blob/HEAD/src/app/%5Bowner%5D/%5Brepo%5D/page.tsx) (Repo chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Next.js UI"
  landing["Repo entry<br/>route<br/>[page.tsx]"]
  workspace["Repo chat<br/>route<br/>[page.tsx]"]
  storage["Storage view<br/>route<br/>[page.tsx]"]
  metrics["Metrics view<br/>route<br/>[page.tsx]"]
  ablation["Ablation view<br/>route<br/>[page.tsx]"]
  chat_ui["Chat UI<br/>components"]
  browse_ui["Repo browser<br/>components"]
  diagram_ui["Diagram tools<br/>components"]
end

subgraph "Browser runtime"
  github["GitHub fetch<br/>source adapter<br/>[github.ts]"]
  indexer["Indexer<br/>pipeline orchestrator<br/>[indexer.ts]"]
  chunking["Chunking<br/>AST splitter<br/>[chunker.ts]"]
  graphing["Code graph<br/>repo graph<br/>[graph.ts]"]
  embed["Embeddings<br/>local model<br/>[embedder.ts]"]
  quant["Quantization<br/>vector compression<br/>[quantize.ts]"]
  store[("IndexedDB store<br/>local persistence<br/>[vectorStore.ts]")]
  retrieval["Hybrid search<br/>retrieval engine<br/>[search.ts]"]
  query["Query shaping<br/>query pipeline<br/>[queryExpansion.ts]"]
  context["Context assembly<br/>prompt builder<br/>[contextAssembly.ts]"]
  llm["Local LLM<br/>browser inference<br/>[llm.ts]"]
  cove["Verification loop<br/>quality gate<br/>[cove.ts]"]
  history["Chat history<br/>session state<br/>[chatHistory.ts]"]
end

subgraph "Optional cloud"
  gemini_api["Gemini route<br/>api route<br/>[route.ts]"]
  groq_api["Groq route<br/>api route<br/>[route.ts]"]
  gemini_vault["Gemini vault<br/>encrypted key store<br/>[gemini-vault.ts]"]
  groq_vault["Groq vault<br/>encrypted key store<br/>[groq-vault.ts]"]
end

subgraph "External sources"
  tree_sitter[("Tree-sitter WASM<br/>parser assets")]
end

landing -->|"repo URL"| github
workspace -->|"uses"| chat_ui
workspace -->|"uses"| browse_ui
workspace -->|"renders"| diagram_ui
github -->|"repo tree"| indexer
indexer -->|"splits"| chunking
chunking -->|"enriches"| graphing
chunking -->|"feeds"| embed
chunking -->|"persists"| store
embed -->|"compresses"| quant
quant -->|"stores"| store
graphing -->|"persists"| store
tree_sitter -->|"parses"| chunking
history -->|"context"| query
query -->|"shapes"| retrieval
store -->|"searches"| retrieval
retrieval -->|"candidates"| context
context -->|"prompt"| llm
llm -->|"answer"| cove
cove -->|"checks"| store
cove -->|"final answer"| chat_ui
chat_ui -->|"saves"| history
chat_ui -.->|"optional"| gemini_api
chat_ui -.->|"optional"| groq_api
gemini_api -->|"keys"| gemini_vault
groq_api -->|"keys"| groq_vault

click landing "https://github.com/floaredor/gitask/blob/main/src/app/page.tsx"
click workspace "https://github.com/floaredor/gitask/blob/main/src/app/[owner]/[repo]/page.tsx"
click storage "https://github.com/floaredor/gitask/blob/main/src/app/storage/page.tsx"
click metrics "https://github.com/floaredor/gitask/blob/main/src/app/metrics/page.tsx"
click ablation "https://github.com/floaredor/gitask/blob/main/src/app/ablation/page.tsx"
click chat_ui "https://github.com/floaredor/gitask/tree/main/src/components/chat"
click browse_ui "https://github.com/floaredor/gitask/tree/main/src/components"
click diagram_ui "https://github.com/floaredor/gitask/tree/main/src/components/diagram"
click github "https://github.com/floaredor/gitask/blob/main/src/lib/github.ts"
click indexer "https://github.com/floaredor/gitask/blob/main/src/lib/indexer.ts"
click chunking "https://github.com/floaredor/gitask/blob/main/src/lib/chunker.ts"
click graphing "https://github.com/floaredor/gitask/blob/main/src/lib/graph.ts"
click embed "https://github.com/floaredor/gitask/blob/main/src/lib/embedder.ts"
click quant "https://github.com/floaredor/gitask/blob/main/src/lib/quantize.ts"
click store "https://github.com/floaredor/gitask/blob/main/src/lib/vectorStore.ts"
click retrieval "https://github.com/floaredor/gitask/blob/main/src/lib/search.ts"
click query "https://github.com/floaredor/gitask/blob/main/src/lib/queryExpansion.ts"
click context "https://github.com/floaredor/gitask/blob/main/src/lib/contextAssembly.ts"
click llm "https://github.com/floaredor/gitask/blob/main/src/lib/llm.ts"
click cove "https://github.com/floaredor/gitask/blob/main/src/lib/cove.ts"
click history "https://github.com/floaredor/gitask/blob/main/src/lib/chatHistory.ts"
click gemini_api "https://github.com/floaredor/gitask/blob/main/src/app/api/gemini/route.ts"
click groq_api "https://github.com/floaredor/gitask/blob/main/src/app/api/groq/route.ts"
click gemini_vault "https://github.com/floaredor/gitask/blob/main/src/lib/gemini-vault.ts"
click groq_vault "https://github.com/floaredor/gitask/blob/main/src/lib/groq-vault.ts"
click tree_sitter "https://github.com/floaredor/gitask/tree/main/public/wasms"

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 landing,workspace,storage,metrics,ablation,chat_ui,browse_ui,diagram_ui toneBlue
class github,indexer,chunking,graphing,embed,quant,store,retrieval,query,context,llm,cove,history toneAmber
class gemini_api,groq_api,gemini_vault,groq_vault toneMint
class tree_sitter toneRose
```

## Components

### Next.js UI

App router pages and browser-facing components

- [Repo entry](https://github.com/floaredor/gitask/blob/HEAD/src/app/page.tsx): route · Landing page and repo URL entry · `src/app/page.tsx`
- [Repo chat](https://github.com/floaredor/gitask/blob/HEAD/src/app/%5Bowner%5D/%5Brepo%5D/page.tsx): route · Main repository Q&A workspace · `src/app/[owner]/[repo]/page.tsx`
- [Storage view](https://github.com/floaredor/gitask/blob/HEAD/src/app/storage/page.tsx): route · Local index inspection page · `src/app/storage/page.tsx`
- [Metrics view](https://github.com/floaredor/gitask/blob/HEAD/src/app/metrics/page.tsx): route · Evaluation and metrics page · `src/app/metrics/page.tsx`
- [Ablation view](https://github.com/floaredor/gitask/blob/HEAD/src/app/ablation/page.tsx): route · Experimental pipeline views · `src/app/ablation/page.tsx`
- [Chat UI](https://github.com/floaredor/gitask/tree/HEAD/src/components/chat): components · Chat input, messages, sidebar, and context panels · `src/components/chat`
- [Repo browser](https://github.com/floaredor/gitask/tree/HEAD/src/components): components · Index browser, file browser, AST view, and progress overlays · `src/components`
- [Diagram tools](https://github.com/floaredor/gitask/tree/HEAD/src/components/diagram): components · Architecture diagram rendering and modal display · `src/components/diagram`

### Browser runtime

Client-side ingestion, retrieval, storage, and inference

- [GitHub fetch](https://github.com/floaredor/gitask/blob/HEAD/src/lib/github.ts): source adapter · Repo tree and file content acquisition · `src/lib/github.ts`
- [Indexer](https://github.com/floaredor/gitask/blob/HEAD/src/lib/indexer.ts): pipeline orchestrator · Coordinates repo ingestion and index build · `src/lib/indexer.ts`
- [Chunking](https://github.com/floaredor/gitask/blob/HEAD/src/lib/chunker.ts): AST splitter · Tree-sitter aware code chunking and summaries · `src/lib/chunker.ts`
- [Code graph](https://github.com/floaredor/gitask/blob/HEAD/src/lib/graph.ts): repo graph · Dependency and definition relationship graph · `src/lib/graph.ts`
- [Embeddings](https://github.com/floaredor/gitask/blob/HEAD/src/lib/embedder.ts): local model · In-browser embedding generation · `src/lib/embedder.ts`
- [Quantization](https://github.com/floaredor/gitask/blob/HEAD/src/lib/quantize.ts): vector compression · Binary vector packing for memory-efficient storage · `src/lib/quantize.ts`
- [IndexedDB store](https://github.com/floaredor/gitask/blob/HEAD/src/lib/vectorStore.ts): local persistence · Browser-local durable vector and repo state storage · `src/lib/vectorStore.ts`
- [Hybrid search](https://github.com/floaredor/gitask/blob/HEAD/src/lib/search.ts): retrieval engine · Dense, sparse, fusion, and rerank retrieval · `src/lib/search.ts`
- [Query shaping](https://github.com/floaredor/gitask/blob/HEAD/src/lib/queryExpansion.ts): query pipeline · Expansion, history enrichment, and safety checks · `src/lib/queryExpansion.ts`
- [Context assembly](https://github.com/floaredor/gitask/blob/HEAD/src/lib/contextAssembly.ts): prompt builder · Builds grounded prompt context with citations · `src/lib/contextAssembly.ts`
- [Local LLM](https://github.com/floaredor/gitask/blob/HEAD/src/lib/llm.ts): browser inference · WebLLM execution in a browser worker · `src/lib/llm.ts`
- [Verification loop](https://github.com/floaredor/gitask/blob/HEAD/src/lib/cove.ts): quality gate · Claim checking and answer revision · `src/lib/cove.ts`
- [Chat history](https://github.com/floaredor/gitask/blob/HEAD/src/lib/chatHistory.ts): session state · Persistent repo-scoped conversation state · `src/lib/chatHistory.ts`

### Optional cloud

BYOK provider routes and key vaults

- [Gemini route](https://github.com/floaredor/gitask/blob/HEAD/src/app/api/gemini/route.ts): api route · Optional BYOK Gemini generation path · `src/app/api/gemini/route.ts`
- [Groq route](https://github.com/floaredor/gitask/blob/HEAD/src/app/api/groq/route.ts): api route · Optional BYOK Groq generation path · `src/app/api/groq/route.ts`
- [Gemini vault](https://github.com/floaredor/gitask/blob/HEAD/src/lib/gemini-vault.ts): encrypted key store · Local encrypted Gemini credential storage · `src/lib/gemini-vault.ts`
- [Groq vault](https://github.com/floaredor/gitask/blob/HEAD/src/lib/groq-vault.ts): encrypted key store · Local encrypted Groq credential storage · `src/lib/groq-vault.ts`

### External sources

GitHub repo input and shipped model/runtime assets

- [Tree-sitter WASM](https://github.com/floaredor/gitask/tree/HEAD/public/wasms): parser assets · Shipped grammar and parser runtime assets · `public/wasms`

## Connections

- Repo entry → GitHub fetch: repo URL · Starts repo acquisition from a pasted GitHub URL
- Repo chat → Chat UI: uses · Main conversation experience
- Repo chat → Repo browser: uses · Repo browsing and indexing inspection
- Repo chat → Diagram tools: renders · Shows architecture diagrams and overlays
- GitHub fetch → Indexer: repo tree · Fetched metadata and file contents enter indexing
- Indexer → Chunking: splits · Turns source files into structured chunks
- Chunking → Code graph: enriches · Builds structural relationships from parsed code
- Chunking → Embeddings: feeds · Chunk text is embedded in-browser
- Chunking → IndexedDB store: persists · Chunk metadata and text are stored locally
- Embeddings → Quantization: compresses · Embeddings are quantized for compact storage
- Quantization → IndexedDB store: stores · Compressed vectors are written to IndexedDB
- Code graph → IndexedDB store: persists · Repository graph is stored with the index
- Tree-sitter WASM → Chunking: parses · Browser-loaded grammars power AST-aware chunking
- Chat history → Query shaping: context · Prior chat turns enrich retrieval queries
- Query shaping → Hybrid search: shapes · Expanded and safety-checked queries enter retrieval
- IndexedDB store → Hybrid search: searches · Dense and sparse lookup run over local index
- Hybrid search → Context assembly: candidates · Top results are assembled into grounded context
- Context assembly → Local LLM: prompt · Final context is sent to generation
- Local LLM → Verification loop: answer · Generated answer enters verification
- Verification loop → IndexedDB store: checks · Claims are verified against the local index
- Verification loop → Chat UI: final answer · Verified response is shown in chat
- Chat UI → Chat history: saves · Conversation state is persisted locally
- Chat UI → Gemini route: optional · Alternate BYOK generation path
- Chat UI → Groq route: optional · Alternate BYOK generation path
- Gemini route → Gemini vault: keys · Uses encrypted local Gemini credentials
- Groq route → Groq vault: keys · Uses encrypted local Groq credentials
