# inegmdev/qrag architecture

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

- Interactive diagram: https://gitdiagram.com/inegmdev/qrag
- Repository: https://github.com/inegmdev/qrag

## Overview

1. **What this repo is**
   - `qrag` is a local-first indexing and retrieval system for teams: one person builds semantic databases once, then everyone else downloads and queries them from AI agents.
   - The core boundary is between **database preparation** and **database consumption**.

2. **Primary runtime and packaging**
   - The main implementation is a **Python package** under `src/qrag`.
   - User entry points are exposed through the **CLI** (`src/qrag/cli.py`), with supporting config, storage, parsing, embedding, and integration modules.
   - Packaging is handled with standard Python tooling (`pyproject.toml`, `setup.py`, `uv.lock`), and there is also an `npm/` package present for JavaScript-side distribution/integration.

3. **Build/indexing pipeline**
   - The build flow takes local input directories (`qrag build -i ... -o version`) and turns them into versioned indexes.
   - Source code goes through `doc_parser.py`, `chunker.py`, and likely tree-sitter-based symbol extraction before being written into a code-oriented database.
   - Documentation files are parsed into section/chunk units and stored separately so code and docs can be searched independently.

4. **Embeddings and semantic search**
   - `embedder.py` is the semantic layer: it generates embeddings locally rather than calling an external service.
   - The README indicates the bundled model is `all-MiniLM-L6-v2`, with optional GPU acceleration for larger installs.
   - Search is therefore a hybrid of **symbolic structure** plus **vector similarity**.

5. **Storage model**
   - Each published version is stored locally under `~/.qrag/<version>/`.
   - The two main artifacts are `code.db` and `docs.db`, both SQLite databases.
   - The active version set is separate from storage; users can keep multiple versions installed and search across all of them simultaneously.

6. **Query path**
   - The CLI supports `search`, `search code`, `search docs`, and `search symbol`.
   - `database.py` is the retrieval boundary: it likely merges results from active databases, deduplicates them, and returns ranked matches.
   - Symbol lookup is exact/structural, while code/docs search is semantic.

7. **Distribution and team sharing**
   - `github_distribution.py` handles the “hub” workflow: listing versions, downloading them, pushing them, and deleting local copies.
   - The repository is configured through `QRAG_GITHUB_URL`, and GitHub auth is required via `gh` or `GITHUB_TOKEN`.
   - This makes the architecture explicitly **publisher/consumer** rather than centralized SaaS: the team hosts databases in a GitHub repo and clients fetch them.

8. **AI agent integration**
   - `mcp_server.py` exposes qrag as tools to external AI clients.
   - The README mentions Claude and Gemini CLI support via `qrag ai setup`, which installs or configures an MCP-style tool bridge.
   - The integration boundary is local: the agent calls qrag-installed tools on the user machine, not a remote API.

9. **User-facing interfaces**
   - The main user interface is the CLI, but there is also a `tui.py` module for terminal-based interaction.
   - `status` and `info` provide operational visibility into which versions are active and whether the databases exist locally.
   - This is a developer-tooling style application, not a web service.

10. **Repository organization for workflows**
   - `docs/` contains the product and architecture docs, including architecture, backlog, handoff, quickstart, and progress tracking.
   - `issues/` contains issue-sized work items that map onto roadmap features like incremental updates, live folder watching, GPU embeddings, and distribution.
   - `tests/` covers the main subsystems: chunking, database behavior, integration, and TUI.

11. **Build and release pipeline**
   - GitHub Actions in `.github/workflows/ci.yml` and `publish.yml` handle validation and release publication.
   - The repo is designed to be installed either for end users or for builders, with separate dependency profiles for CPU vs GPU-heavy builds.
   - `scripts/download_model.py` and `tools/afk.py` are supporting utilities rather than core architecture.

12. **Important architectural takeaway**
   - The system is centered on **local immutable-ish versioned indexes** plus a **GitHub-backed distribution channel**.
   - All runtime behavior flows from that: build locally, store per version, activate one or more versions, search across them, and expose the result to AI agents through a local MCP integration.

Main entry points: [`src/qrag/cli.py`](https://github.com/inegmdev/qrag/blob/main/src/qrag/cli.py) (CLI), [`src/qrag/database.py`](https://github.com/inegmdev/qrag/blob/main/src/qrag/database.py) (Database), [`src/qrag/github_distribution.py`](https://github.com/inegmdev/qrag/blob/main/src/qrag/github_distribution.py) (GitHub Distribution), [`src/qrag/chunker.py`](https://github.com/inegmdev/qrag/blob/main/src/qrag/chunker.py) (Chunker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & Indexing"]
  node_parser["Doc Parser<br/>[doc_parser.py]"]
  node_chunker["Chunker<br/>chunking<br/>[chunker.py]"]
  node_embedder(("Embedder<br/>embeddings<br/>[embedder.py]"))
  node_config["Config<br/>settings<br/>[config.py]"]
end

subgraph group_storage["Databases"]
  node_database[("Database<br/>retrieval<br/>[database.py]")]
end

subgraph group_distribution["Sharing"]
  node_distribution["GitHub Distribution<br/>sync"]
end

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_tui["TUI<br/>[tui.py]"]
  node_mcp["MCP Server<br/>agent bridge<br/>[mcp_server.py]"]
end

subgraph group_packaging["Packaging"]
  node_setup["Packaging<br/>build system<br/>[setup.py]"]
  node_pyproject["Pyproject<br/>build config<br/>[pyproject.toml]"]
  node_npm["npm Package<br/>jsii<br/>[package.json]"]
end

node_readme["README<br/>docs<br/>[README.md]"]
node_architecture["Architecture<br/>docs<br/>[ARCHITECTURE.md]"]
node_backlog["Backlog<br/>docs<br/>[BACKLOG.md]"]
node_ci["CI<br/>workflow<br/>[ci.yml]"]
node_publish["Publish<br/>workflow<br/>[publish.yml]"]

node_cli -->|"loads"| node_config
node_cli -->|"builds docs"| node_parser
node_cli -->|"builds code"| node_chunker
node_cli -->|"embeds"| node_embedder
node_cli -->|"queries"| node_database
node_cli -->|"syncs"| node_distribution
node_cli -.->|"offers"| node_tui
node_cli -.->|"exposes"| node_mcp
node_parser -->|"normalizes"| node_chunker
node_chunker -->|"vectors"| node_embedder
node_embedder -->|"stores"| node_database
node_database -->|"fetches versions"| node_distribution
node_distribution -->|"installs"| node_database
node_readme -.->|"documents"| node_cli
node_architecture -.->|"describes"| node_database
node_backlog -.->|"plans"| node_distribution
node_pyproject -.->|"packages"| node_setup
node_npm -.->|"integrates"| node_cli
node_ci -.->|"validates"| node_setup
node_publish -.->|"releases"| node_distribution

click node_cli "https://github.com/inegmdev/qrag/blob/main/src/qrag/cli.py"
click node_tui "https://github.com/inegmdev/qrag/blob/main/src/qrag/tui.py"
click node_mcp "https://github.com/inegmdev/qrag/blob/main/src/qrag/mcp_server.py"
click node_parser "https://github.com/inegmdev/qrag/blob/main/src/qrag/doc_parser.py"
click node_chunker "https://github.com/inegmdev/qrag/blob/main/src/qrag/chunker.py"
click node_embedder "https://github.com/inegmdev/qrag/blob/main/src/qrag/embedder.py"
click node_config "https://github.com/inegmdev/qrag/blob/main/src/qrag/config.py"
click node_database "https://github.com/inegmdev/qrag/blob/main/src/qrag/database.py"
click node_distribution "https://github.com/inegmdev/qrag/blob/main/src/qrag/github_distribution.py"
click node_setup "https://github.com/inegmdev/qrag/blob/main/setup.py"
click node_pyproject "https://github.com/inegmdev/qrag/blob/main/pyproject.toml"
click node_npm "https://github.com/inegmdev/qrag/blob/main/npm/package.json"
click node_readme "https://github.com/inegmdev/qrag/blob/main/README.md"
click node_architecture "https://github.com/inegmdev/qrag/blob/main/docs/ARCHITECTURE.md"
click node_backlog "https://github.com/inegmdev/qrag/blob/main/docs/BACKLOG.md"
click node_ci "https://github.com/inegmdev/qrag/blob/main/.github/workflows/ci.yml"
click node_publish "https://github.com/inegmdev/qrag/blob/main/.github/workflows/publish.yml"

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_parser,node_chunker,node_embedder,node_config toneBlue
class node_database toneAmber
class node_distribution toneMint
class node_cli,node_tui,node_mcp toneRose
class node_setup,node_pyproject,node_npm toneIndigo
class node_readme,node_architecture,node_backlog,node_ci,node_publish toneNeutral
```

## Components

### Build & Indexing

Local preparation pipeline that turns source directories into versioned databases.

- [Doc Parser](https://github.com/inegmdev/qrag/blob/main/src/qrag/doc_parser.py): parser · Turns documents into searchable sections and chunks. · `src/qrag/doc_parser.py`
- [Chunker](https://github.com/inegmdev/qrag/blob/main/src/qrag/chunker.py): chunking · Splits content into retrieval-sized units for indexing. · `src/qrag/chunker.py`
- [Embedder](https://github.com/inegmdev/qrag/blob/main/src/qrag/embedder.py): embeddings · Generates local semantic embeddings for code and docs. · `src/qrag/embedder.py`
- [Config](https://github.com/inegmdev/qrag/blob/main/src/qrag/config.py): settings · Holds runtime and storage configuration for builds and queries. · `src/qrag/config.py`

### Databases

Versioned local SQLite stores and retrieval logic.

- [Database](https://github.com/inegmdev/qrag/blob/main/src/qrag/database.py): retrieval · Retrieval boundary that merges active versions and ranks results. · `src/qrag/database.py`

### Sharing

GitHub-backed publishing and installation of database versions.

- [GitHub Distribution](https://github.com/inegmdev/qrag/blob/main/src/qrag/github_distribution.py): sync · Lists, downloads, publishes, and removes versioned database bundles. · `src/qrag/github_distribution.py`

### Interfaces

User and agent entry points for search and control.

- [CLI](https://github.com/inegmdev/qrag/blob/main/src/qrag/cli.py): entrypoint · Main command-line entry point for build, search, status, and info workflows. · `src/qrag/cli.py`
- [TUI](https://github.com/inegmdev/qrag/blob/main/src/qrag/tui.py): ui · Terminal interface for interactive usage. · `src/qrag/tui.py`
- [MCP Server](https://github.com/inegmdev/qrag/blob/main/src/qrag/mcp_server.py): agent bridge · Exposes qrag capabilities to external AI clients through local tools. · `src/qrag/mcp_server.py`

### Packaging

Python and npm distribution surfaces.

- [Packaging](https://github.com/inegmdev/qrag/blob/main/setup.py): build system · Python packaging and installation metadata for the project. · `setup.py`
- [Pyproject](https://github.com/inegmdev/qrag/blob/main/pyproject.toml): build config · Primary Python project and dependency configuration. · `pyproject.toml`
- [npm Package](https://github.com/inegmdev/qrag/blob/main/npm/package.json): jsii · JavaScript-side package and distribution integration surface. · `npm/package.json`

### Other components

- [README](https://github.com/inegmdev/qrag/blob/main/README.md): docs · High-level product and usage documentation. · `README.md`
- [Architecture](https://github.com/inegmdev/qrag/blob/main/docs/ARCHITECTURE.md): docs · System architecture and design notes. · `docs/ARCHITECTURE.md`
- [Backlog](https://github.com/inegmdev/qrag/blob/main/docs/BACKLOG.md): docs · Planned work items and roadmap decomposition. · `docs/BACKLOG.md`
- [CI](https://github.com/inegmdev/qrag/blob/main/.github/workflows/ci.yml): workflow · Validation workflow for tests and checks. · `.github/workflows/ci.yml`
- [Publish](https://github.com/inegmdev/qrag/blob/main/.github/workflows/publish.yml): workflow · Release workflow for publishing distributable artifacts. · `.github/workflows/publish.yml`

## Connections

- CLI → Config: loads · CLI reads runtime settings and active version configuration.
- CLI → Doc Parser: builds docs · Build commands parse documentation inputs into indexed units.
- CLI → Chunker: builds code · Build commands chunk code-oriented inputs for indexing.
- CLI → Embedder: embeds · Build and search flows use local embeddings.
- CLI → Database: queries · Search commands route through the retrieval boundary.
- CLI → GitHub Distribution: syncs · CLI supports version listing, download, publish, and cleanup.
- CLI → TUI: offers · CLI and TUI provide alternative local user interfaces.
- CLI → MCP Server: exposes · CLI can configure local agent-tool integration.
- Doc Parser → Chunker: normalizes · Document parsing feeds chunking and sectionization.
- Chunker → Embedder: vectors · Chunked content is converted into embeddings.
- Embedder → Database: stores · Semantic representations are written into the local databases.
- Database → GitHub Distribution: fetches versions · Active or missing versions can be pulled from GitHub-backed storage.
- GitHub Distribution → Database: installs · Downloaded versioned databases become queryable local stores.
- README → CLI: documents · README describes the primary commands and workflows.
- Architecture → Database: describes · Architecture docs explain the versioned storage and retrieval model.
- Backlog → GitHub Distribution: plans · Backlog tracks sharing, sync, and publish enhancements.
- Pyproject → Packaging: packages · Python packaging metadata drives installation and build behavior.
- npm Package → CLI: integrates · npm package supports JavaScript-side consumption and integration.
- CI → Packaging: validates · CI checks packaging and project integrity.
- Publish → GitHub Distribution: releases · Publish workflow ships distribution artifacts and release outputs.