# marianoorlei/qmd architecture

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

- Interactive diagram: https://gitdiagram.com/marianoorlei/qmd
- Repository: https://github.com/marianoorlei/qmd

## Overview

QMD is a local document-search engine exposed through a CLI, SDK, and MCP server. Users configure collections of Markdown files, index them, then retrieve documents or search by keywords, semantics, or hybrid ranking. The search path combines typed query expansion, BM25 and vector retrieval, reciprocal-rank fusion, and optional LLM reranking. Metadata filtering/discovery and model integrations are supporting capabilities. The repository also contains a separate model fine-tuning workflow; its internal steps are summarized at directory level because its sources were not inspected in full.

Main entry points: [`src/index.ts`](https://github.com/marianoorlei/qmd/blob/main/src/index.ts) (QMD SDK), [`src/store.ts`](https://github.com/marianoorlei/qmd/blob/main/src/store.ts) (Document indexing), [`src/cli/qmd.ts`](https://github.com/marianoorlei/qmd/blob/main/src/cli/qmd.ts) (QMD CLI), [`src/mcp/server.ts`](https://github.com/marianoorlei/qmd/blob/main/src/mcp/server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["QMD CLI<br/>[qmd.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_sdk["QMD SDK<br/>[index.ts]"]
end

subgraph group_indexing["Collections and indexing"]
  node_collection_config["Collection config<br/>[collections.ts]"]
  node_indexing_store["Document indexing<br/>[store.ts]"]
  node_processors["Command processors<br/>[processors.ts]"]
end

subgraph group_retrieval["Search and ranking"]
  node_query_expansion["Query expansion<br/>[llm.ts]"]
  node_hybrid_search["Hybrid search<br/>[store.ts]"]
  node_fusion_rerank["Fusion and reranking<br/>[store.ts]"]
  node_local_models["Local LLM models<br/>[llm.ts]"]
  node_remote_embeddings["Remote embeddings<br/>[remote-embed.ts]"]
  node_remote_reranker["Remote reranker<br/>[jev.ts]"]
end

subgraph group_platform["Index and metadata"]
  node_metadata_extract["Metadata extraction<br/>[metadata.ts]"]
  node_metadata_query["Metadata filters<br/>[metadata-filter.ts]"]
  node_metadata_store["Metadata discovery<br/>[metadata-store.ts]"]
  node_document_store[("Document and vector store<br/>[store.ts]")]
  node_sqlite[("SQLite access<br/>[db.ts]")]
end

subgraph group_tuning["Model fine-tuning"]
  node_finetune_data["Training data preparation"]
  node_finetune_reward["Reward modeling<br/>[reward.py]"]
  node_finetune_train["Model training<br/>[train.py]"]
  node_finetune_eval["Evaluation"]
end

node_user(("User or agent"))

node_user -->|"runs commands"| node_cli
node_user -->|"connects tools"| node_mcp
node_user -->|"calls API"| node_sdk
node_cli -->|"loads config"| node_collection_config
node_cli -->|"reindexes files"| node_indexing_store
node_cli -->|"creates processor"| node_processors
node_mcp -->|"handles search"| node_sdk
node_mcp -->|"loads config"| node_collection_config
node_sdk -->|"loads config"| node_collection_config
node_sdk -->|"reindexes collection"| node_indexing_store
node_sdk -->|"dispatches queries"| node_hybrid_search
node_indexing_store -.->|"writes index"| node_document_store
node_indexing_store -.->|"extracts metadata"| node_metadata_extract
node_indexing_store -.->|"runs processors"| node_processors
node_hybrid_search -->|"expands queries"| node_query_expansion
node_hybrid_search -->|"fuses results"| node_fusion_rerank
node_hybrid_search -.->|"retrieves candidates"| node_document_store
node_fusion_rerank -.->|"reranks locally"| node_local_models
node_fusion_rerank -.->|"reranks remotely"| node_remote_reranker
node_query_expansion -->|"uses remote model"| node_remote_embeddings
node_metadata_store -->|"compiles filters"| node_metadata_query
node_metadata_store -.->|"queries database"| node_sqlite
node_document_store -->|"uses SQLite"| node_sqlite
node_finetune_data -.->|"prepares training data"| node_finetune_train
node_finetune_reward -->|"scores training"| node_finetune_train
node_finetune_train -.->|"evaluates models"| node_finetune_eval

click node_cli "https://github.com/marianoorlei/qmd/blob/main/src/cli/qmd.ts"
click node_mcp "https://github.com/marianoorlei/qmd/blob/main/src/mcp/server.ts"
click node_sdk "https://github.com/marianoorlei/qmd/blob/main/src/index.ts"
click node_collection_config "https://github.com/marianoorlei/qmd/blob/main/src/collections.ts"
click node_indexing_store "https://github.com/marianoorlei/qmd/blob/main/src/store.ts"
click node_processors "https://github.com/marianoorlei/qmd/blob/main/src/processors.ts"
click node_query_expansion "https://github.com/marianoorlei/qmd/blob/main/src/llm.ts"
click node_hybrid_search "https://github.com/marianoorlei/qmd/blob/main/src/store.ts"
click node_fusion_rerank "https://github.com/marianoorlei/qmd/blob/main/src/store.ts"
click node_local_models "https://github.com/marianoorlei/qmd/blob/main/src/llm.ts"
click node_remote_embeddings "https://github.com/marianoorlei/qmd/blob/main/src/remote-embed.ts"
click node_remote_reranker "https://github.com/marianoorlei/qmd/blob/main/src/jev.ts"
click node_metadata_extract "https://github.com/marianoorlei/qmd/blob/main/src/metadata.ts"
click node_metadata_query "https://github.com/marianoorlei/qmd/blob/main/src/metadata-filter.ts"
click node_metadata_store "https://github.com/marianoorlei/qmd/blob/main/src/metadata-store.ts"
click node_document_store "https://github.com/marianoorlei/qmd/blob/main/src/store.ts"
click node_sqlite "https://github.com/marianoorlei/qmd/blob/main/src/db.ts"
click node_finetune_data "https://github.com/marianoorlei/qmd/tree/main/finetune/dataset"
click node_finetune_reward "https://github.com/marianoorlei/qmd/blob/main/finetune/reward.py"
click node_finetune_train "https://github.com/marianoorlei/qmd/blob/main/finetune/train.py"
click node_finetune_eval "https://github.com/marianoorlei/qmd/tree/main/finetune/jobs"

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_cli,node_mcp,node_sdk,node_user toneBlue
class node_collection_config,node_indexing_store,node_processors toneAmber
class node_query_expansion,node_hybrid_search,node_fusion_rerank,node_local_models,node_remote_embeddings,node_remote_reranker toneMint
class node_metadata_extract,node_metadata_query,node_metadata_store,node_document_store,node_sqlite toneRose
class node_finetune_data,node_finetune_reward,node_finetune_train,node_finetune_eval toneIndigo
```

## Components

### User interfaces

- [QMD CLI](https://github.com/marianoorlei/qmd/blob/main/src/cli/qmd.ts): `src/cli/qmd.ts`
- [MCP server](https://github.com/marianoorlei/qmd/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [QMD SDK](https://github.com/marianoorlei/qmd/blob/main/src/index.ts): `src/index.ts`

### Collections and indexing

- [Collection config](https://github.com/marianoorlei/qmd/blob/main/src/collections.ts): `src/collections.ts`
- [Document indexing](https://github.com/marianoorlei/qmd/blob/main/src/store.ts): `src/store.ts`
- [Command processors](https://github.com/marianoorlei/qmd/blob/main/src/processors.ts): `src/processors.ts`

### Search and ranking

- [Query expansion](https://github.com/marianoorlei/qmd/blob/main/src/llm.ts): `src/llm.ts`
- [Hybrid search](https://github.com/marianoorlei/qmd/blob/main/src/store.ts): `src/store.ts`
- [Fusion and reranking](https://github.com/marianoorlei/qmd/blob/main/src/store.ts): `src/store.ts`
- [Local LLM models](https://github.com/marianoorlei/qmd/blob/main/src/llm.ts): `src/llm.ts`
- [Remote embeddings](https://github.com/marianoorlei/qmd/blob/main/src/remote-embed.ts): `src/remote-embed.ts`
- [Remote reranker](https://github.com/marianoorlei/qmd/blob/main/src/jev.ts): `src/jev.ts`

### Index and metadata

- [Metadata extraction](https://github.com/marianoorlei/qmd/blob/main/src/metadata.ts): `src/metadata.ts`
- [Metadata filters](https://github.com/marianoorlei/qmd/blob/main/src/metadata-filter.ts): `src/metadata-filter.ts`
- [Metadata discovery](https://github.com/marianoorlei/qmd/blob/main/src/metadata-store.ts): `src/metadata-store.ts`
- [Document and vector store](https://github.com/marianoorlei/qmd/blob/main/src/store.ts): `src/store.ts`
- [SQLite access](https://github.com/marianoorlei/qmd/blob/main/src/db.ts): `src/db.ts`

### Model fine-tuning

- [Training data preparation](https://github.com/marianoorlei/qmd/tree/main/finetune/dataset): `finetune/dataset`
- [Reward modeling](https://github.com/marianoorlei/qmd/blob/main/finetune/reward.py): `finetune/reward.py`
- [Model training](https://github.com/marianoorlei/qmd/blob/main/finetune/train.py): `finetune/train.py`
- [Evaluation](https://github.com/marianoorlei/qmd/tree/main/finetune/jobs): `finetune/jobs`

### Other components

- **User or agent**

## Connections

- User or agent → QMD CLI: runs commands
- User or agent → MCP server: connects tools
- User or agent → QMD SDK: calls API (evidence: `src/index.ts`)
- QMD CLI → Collection config: loads config (evidence: `src/cli/qmd.ts`)
- QMD CLI → Document indexing: reindexes files (evidence: `src/cli/qmd.ts`)
- QMD CLI → Command processors: creates processor (evidence: `src/cli/qmd.ts`)
- MCP server → QMD SDK: handles search (evidence: `src/mcp/server.ts`)
- MCP server → Collection config: loads config (evidence: `src/mcp/server.ts`)
- QMD SDK → Collection config: loads config (evidence: `src/index.ts`)
- QMD SDK → Document indexing: reindexes collection (evidence: `src/index.ts`)
- QMD SDK → Hybrid search: dispatches queries (evidence: `src/index.ts`)
- Document indexing → Document and vector store: writes index (evidence: `src/store.ts`)
- Document indexing → Metadata extraction: extracts metadata (evidence: `src/store.ts`)
- Document indexing → Command processors: runs processors (evidence: `src/store.ts`)
- Hybrid search → Query expansion: expands queries (evidence: `src/store.ts`)
- Hybrid search → Fusion and reranking: fuses results (evidence: `src/store.ts`)
- Hybrid search → Document and vector store: retrieves candidates (evidence: `src/store.ts`)
- Fusion and reranking → Local LLM models: reranks locally (evidence: `src/store.ts`)
- Fusion and reranking → Remote reranker: reranks remotely
- Query expansion → Remote embeddings: uses remote model (evidence: `src/llm.ts`)
- Metadata discovery → Metadata filters: compiles filters (evidence: `src/metadata-store.ts`)
- Metadata discovery → SQLite access: queries database (evidence: `src/metadata-store.ts`)
- Document and vector store → SQLite access: uses SQLite (evidence: `src/store.ts`)
- Training data preparation → Model training: prepares training data
- Reward modeling → Model training: scores training (evidence: `finetune/train.py`)
- Model training → Evaluation: evaluates models
