# gkatenin/wiki-rag architecture

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

- Interactive diagram: https://gitdiagram.com/gkatenin/wiki-rag
- Repository: https://github.com/gkatenin/wiki-rag

## Overview

#### Purpose and execution
This repository is a minimal Go command-line RAG pipeline for retrieving Wikipedia content and producing an LLM-generated answer. The executable entry point is `main.go`; users provide `-query` and optional `-lang` flags. The system is designed around on-demand retrieval rather than a persistent corpus or web service.

#### CLI orchestration
`main.go` owns the top-level control flow: validate input, fetch a relevant Wikipedia article, chunk/index its text, retrieve context for the query, then pass that context to an LLM reader. It is the integration boundary between command-line input and the retrieval/generation stages.
- `main.go`

#### Wikipedia acquisition boundary
Wikipedia access is isolated in `wiki.go`. This layer uses Go HTTP facilities to search/fetch article material for a selected language, keeping remote Wikipedia interaction separate from retrieval and inference logic. It is the primary external network dependency.
- `wiki.go`
- `main.go`

#### Document preparation
Article content is divided into overlapping character-based chunks before indexing. Overlap preserves neighboring context across chunk boundaries, which is important because retrieved chunks become the prompt evidence supplied to generation. Shared text/chunk handling is likely centralized in utility code.
- `utils.go`
- `wiki.go`

#### Retrieval and ranking
`bm25.go` implements lexical relevance scoring for the fetched article chunks. This is the core retrieval stage: the query is compared against chunk content, and the strongest passages are selected as grounded context. The repository’s RAG scope is therefore per-request and per-article, rather than a durable multi-document index.
- `bm25.go`
- `main.go`

#### Embedding and model runtime
The project depends on `github.com/kelindar/search` for semantic search/embedding capabilities and uses GGUF-compatible BERT-style models through llama.cpp bindings backed by `purego`, avoiding cgo. Model loading and inference-facing integration are represented by the LLM reader layer, with dependency versions pinned in Go modules.
- `llm-reader.go`
- `go.mod`
- `go.sum`

#### Context-to-answer generation
`llm-reader.go` forms the generation boundary: it receives selected context plus the original query and invokes the local model runtime to produce the final answer printed by the CLI. Retrieval output should be treated as untrusted remote text; generation behavior, prompt construction, and model availability are operationally dependent on local GGUF model assets/runtime support.
- `llm-reader.go`
- `main.go`

#### Key flow and operational boundaries
Control flow is: CLI flags → Wikipedia HTTP retrieval → article chunking → BM25/semantic ranking → top-context assembly → local LLM answer output. External services are Wikipedia over HTTP; inference is local through llama.cpp/GGUF rather than a hosted model API. The Go binary is portable in principle, but execution materially requires a compatible local embedding/generation model and the native runtime access expected by the search dependency.

Main entry points: [`main.go`](https://github.com/gkatenin/wiki-rag/blob/main/main.go) (RAG command), [`wiki.go`](https://github.com/gkatenin/wiki-rag/blob/main/wiki.go) (Wikipedia client), [`llm-reader.go`](https://github.com/gkatenin/wiki-rag/blob/main/llm-reader.go) (LLM reader), [`bm25.go`](https://github.com/gkatenin/wiki-rag/blob/main/bm25.go) (BM25 ranker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI orchestration"]
  node_user(("User query<br/>CLI input"))
  node_main["RAG command<br/>Go entry point<br/>[main.go]"]
  node_answer_output["Answer output<br/>terminal output"]
end

subgraph group_retrieval["On-demand retrieval"]
  node_wiki_client["Wikipedia client<br/>HTTP acquisition<br/>[wiki.go]"]
  node_chunker["Article chunker<br/>text preparation<br/>[utils.go]"]
  node_bm25["BM25 ranker<br/>lexical retrieval<br/>[bm25.go]"]
  node_top_context["Top context<br/>prompt evidence"]
end

subgraph group_inference["Local inference"]
  node_llm_reader["LLM reader<br/>generation boundary<br/>[llm-reader.go]"]
  node_local_models[("GGUF model assets<br/>local model files")]
  node_llama_runtime{{"llama.cpp runtime<br/>local inference runtime"}}
  node_search_dependency["Search dependency<br/>semantic search library<br/>[go.mod]"]
end

node_wikipedia{{"Wikipedia<br/>external HTTP service"}}

node_user -->|"-query, -lang"| node_main
node_main -->|"fetch article"| node_wiki_client
node_wiki_client -->|"HTTP search/fetch"| node_wikipedia
node_wikipedia -->|"article text"| node_wiki_client
node_wiki_client -->|"article content"| node_chunker
node_chunker -->|"overlapping chunks"| node_bm25
node_main -->|"query"| node_bm25
node_bm25 -->|"ranked passages"| node_top_context
node_main -->|"query and context"| node_llm_reader
node_top_context -->|"grounding evidence"| node_llm_reader
node_llm_reader -->|"inference request"| node_llama_runtime
node_local_models -->|"loads GGUF models"| node_llama_runtime
node_search_dependency -.->|"purego-backed access"| node_llama_runtime
node_llm_reader -->|"generated answer"| node_answer_output

click node_main "https://github.com/gkatenin/wiki-rag/blob/main/main.go"
click node_wiki_client "https://github.com/gkatenin/wiki-rag/blob/main/wiki.go"
click node_chunker "https://github.com/gkatenin/wiki-rag/blob/main/utils.go"
click node_bm25 "https://github.com/gkatenin/wiki-rag/blob/main/bm25.go"
click node_llm_reader "https://github.com/gkatenin/wiki-rag/blob/main/llm-reader.go"
click node_search_dependency "https://github.com/gkatenin/wiki-rag/blob/main/go.mod"

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_user,node_main,node_answer_output toneBlue
class node_wiki_client,node_chunker,node_bm25,node_top_context toneAmber
class node_llm_reader,node_local_models,node_llama_runtime,node_search_dependency toneMint
class node_wikipedia toneNeutral
```

## Components

### CLI orchestration

- **User query**: CLI input · Query and optional language flags.
- [RAG command](https://github.com/gkatenin/wiki-rag/blob/main/main.go): Go entry point · Coordinates fetch, retrieval, and answer output. · `main.go`
- **Answer output**: terminal output

### On-demand retrieval

- [Wikipedia client](https://github.com/gkatenin/wiki-rag/blob/main/wiki.go): HTTP acquisition · Searches and fetches article material for the selected language. · `wiki.go`
- [Article chunker](https://github.com/gkatenin/wiki-rag/blob/main/utils.go): text preparation · Creates overlapping character-based chunks. · `utils.go`
- [BM25 ranker](https://github.com/gkatenin/wiki-rag/blob/main/bm25.go): lexical retrieval · Scores article chunks against the query. · `bm25.go`
- **Top context**: prompt evidence · Selected passages from the fetched article.

### Local inference

- [LLM reader](https://github.com/gkatenin/wiki-rag/blob/main/llm-reader.go): generation boundary · Builds a prompt from query and retrieved context, then generates an answer. · `llm-reader.go`
- **GGUF model assets**: local model files · Compatible embedding and generation models are required at runtime.
- **llama.cpp runtime**: local inference runtime · GGUF-compatible model access through purego bindings.
- [Search dependency](https://github.com/gkatenin/wiki-rag/blob/main/go.mod): semantic search library · Provides embedding and semantic-search capabilities. · `go.mod`

### Other components

- **Wikipedia**: external HTTP service

## Connections

- User query → RAG command: -query, -lang
- RAG command → Wikipedia client: fetch article
- Wikipedia client → Wikipedia: HTTP search/fetch
- Wikipedia → Wikipedia client: article text
- Wikipedia client → Article chunker: article content
- Article chunker → BM25 ranker: overlapping chunks
- RAG command → BM25 ranker: query
- BM25 ranker → Top context: ranked passages
- RAG command → LLM reader: query and context
- Top context → LLM reader: grounding evidence
- LLM reader → llama.cpp runtime: inference request
- GGUF model assets → llama.cpp runtime: loads GGUF models
- Search dependency → llama.cpp runtime: purego-backed access
- LLM reader → Answer output: generated answer