How floaredor/gitask works
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: chat Chat UI · chunker.ts Chunking · vectorStore.ts IndexedDB store · page.tsx Repo chat
Components 26
Next.js UI
App router pages and browser-facing components
- Repo entry · Landing page and repo URL entry
src/app/page.tsx - Repo chat · Main repository Q&A workspace
src/app/[owner]/[repo]/page.tsx - Storage view · Local index inspection page
src/app/storage/page.tsx - Metrics view · Evaluation and metrics page
src/app/metrics/page.tsx - Ablation view · Experimental pipeline views
src/app/ablation/page.tsx - Chat UI · Chat input, messages, sidebar, and context panels
src/components/chat - Repo browser · Index browser, file browser, AST view, and progress overlays
src/components - Diagram tools · Architecture diagram rendering and modal display
src/components/diagram
Browser runtime
Client-side ingestion, retrieval, storage, and inference
- GitHub fetch · Repo tree and file content acquisition
src/lib/github.ts - Indexer · Coordinates repo ingestion and index build
src/lib/indexer.ts - Chunking · Tree-sitter aware code chunking and summaries
src/lib/chunker.ts - Code graph · Dependency and definition relationship graph
src/lib/graph.ts - Embeddings · In-browser embedding generation
src/lib/embedder.ts - Quantization · Binary vector packing for memory-efficient storage
src/lib/quantize.ts - IndexedDB store · Browser-local durable vector and repo state storage
src/lib/vectorStore.ts - Hybrid search · Dense, sparse, fusion, and rerank retrieval
src/lib/search.ts - Query shaping · Expansion, history enrichment, and safety checks
src/lib/queryExpansion.ts - Context assembly · Builds grounded prompt context with citations
src/lib/contextAssembly.ts - Local LLM · WebLLM execution in a browser worker
src/lib/llm.ts - Verification loop · Claim checking and answer revision
src/lib/cove.ts - Chat history · Persistent repo-scoped conversation state
src/lib/chatHistory.ts
Optional cloud
BYOK provider routes and key vaults
- Gemini route · Optional BYOK Gemini generation path
src/app/api/gemini/route.ts - Groq route · Optional BYOK Groq generation path
src/app/api/groq/route.ts - Gemini vault · Local encrypted Gemini credential storage
src/lib/gemini-vault.ts - Groq vault · Local encrypted Groq credential storage
src/lib/groq-vault.ts
External sources
GitHub repo input and shipped model/runtime assets
- Tree-sitter WASM · Shipped grammar and parser runtime assets
public/wasms
Connections 26
- 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