# refone/tiny-rag architecture

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

- Interactive diagram: https://gitdiagram.com/refone/tiny-rag
- Repository: https://github.com/refone/tiny-rag

## Overview

Shop Assistant Agent ingests PDF and Markdown documents into a searchable knowledge base, then answers user queries using vectorization, three-way retrieval, and generation. The documented import graph routes PDFs through MinerU, processes Markdown images, splits and recognizes content, then embeds and persists it. Shared configuration, model, storage, and tracing modules support these stages. The query, API, and web implementations are not present in the sampled source; query stages are shown only at the level documented in the README.

Main entry points: [`src/processor/import_processor/main_graph.py`](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/main_graph.py) (Import workflow), [`src/processor/import_processor/nodes/node_md_img.py`](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_md_img.py) (Image processing), [`src/processor/import_processor/nodes/node_entry.py`](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_entry.py) (File detection), [`src/processor/import_processor/nodes/node_pdf_to_md.py`](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_pdf_to_md.py) (PDF conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Document ingestion"]
  node_import_graph["Import workflow<br/>[main_graph.py]"]
  node_import_state["Import state<br/>[state.py]"]
  node_entry["File detection<br/>[node_entry.py]"]
  node_pdf_convert["PDF conversion<br/>[node_pdf_to_md.py]"]
  node_image_process["Image processing<br/>[node_md_img.py]"]
  node_document_split["Document splitting"]
  node_item_recognition["Item recognition"]
  node_embedding["Embedding"]
  node_milvus_upsert["Vector persistence"]
end

subgraph group_query["Query answering"]
  node_query_vectorize["Query vectorization"]
  node_retrieval["Three-way retrieval"]
  node_answer["Answer generation"]
end

subgraph group_shared["Shared services"]
  node_vlm["Vision-language model<br/>[vlm.py]"]
  node_minio_client["Image object storage<br/>[minio_client.py]"]
  node_env_config["Environment config<br/>[env_config.py]"]
  node_app_config["Application config<br/>[app_config.py]"]
  node_doc_type["Document types<br/>[doc_type.py]"]
  node_prompt_loader["Prompt loading<br/>[load_prompt.py]"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_node_tracing["Node tracing<br/>[node_utils.py]"]
  node_task_tracking["Task tracking<br/>[task_utils.py]"]
  node_logging["Logging<br/>[logging_utils.py]"]
end

node_user(("Assistant user"))
node_mineru["MinerU service"]
node_milvus[("Milvus")]

node_import_graph -->|"dispatches first"| node_entry
node_import_graph -->|"routes PDFs"| node_pdf_convert
node_import_graph -->|"routes Markdown"| node_image_process
node_import_graph -->|"dispatches after images"| node_document_split
node_import_graph -->|"dispatches after split"| node_item_recognition
node_import_graph -->|"dispatches after recognition"| node_embedding
node_import_graph -->|"dispatches after embedding"| node_milvus_upsert
node_entry -->|"updates"| node_import_state
node_pdf_convert -->|"uploads and polls"| node_mineru
node_pdf_convert -->|"writes Markdown path"| node_import_state
node_image_process -->|"requests image summaries"| node_vlm
node_image_process -->|"loads image prompt"| node_prompt_loader
node_image_process -->|"uploads images"| node_minio_client
node_image_process -->|"checks image formats"| node_app_config
node_image_process -->|"reads and updates"| node_import_state
node_milvus_upsert -->|"persists vectors"| node_milvus
node_user -->|"submits query"| node_query_vectorize
node_query_vectorize -->|"provides query vectors"| node_retrieval
node_retrieval -->|"retrieves matches"| node_milvus
node_retrieval -->|"provides retrieved context"| node_answer
node_answer -->|"returns answer"| node_user
node_vlm -->|"reads model settings"| node_env_config
node_minio_client -->|"reads storage settings"| node_env_config
node_entry -->|"detects file type"| node_doc_type
node_node_tracing -->|"records node status"| node_task_tracking
node_node_tracing -->|"logs node activity"| node_logging
node_logging -->|"reads logging settings"| node_env_config

click node_import_graph "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/main_graph.py"
click node_import_state "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/state.py"
click node_entry "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_entry.py"
click node_pdf_convert "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_pdf_to_md.py"
click node_image_process "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_md_img.py"
click node_document_split "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_document_split.py"
click node_item_recognition "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_item_name_recognize.py"
click node_embedding "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_bge_embedding.py"
click node_milvus_upsert "https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_upsert_milvus.py"
click node_query_vectorize "https://github.com/refone/tiny-rag/tree/main/src/processor/query_processor"
click node_retrieval "https://github.com/refone/tiny-rag/tree/main/src/processor/query_processor"
click node_answer "https://github.com/refone/tiny-rag/tree/main/src/processor/query_processor"
click node_vlm "https://github.com/refone/tiny-rag/blob/main/src/common/model/vlm.py"
click node_minio_client "https://github.com/refone/tiny-rag/blob/main/src/common/client/minio_client.py"
click node_env_config "https://github.com/refone/tiny-rag/blob/main/src/common/config/env_config.py"
click node_app_config "https://github.com/refone/tiny-rag/blob/main/src/common/config/app_config.py"
click node_doc_type "https://github.com/refone/tiny-rag/blob/main/src/common/enum/doc_type.py"
click node_prompt_loader "https://github.com/refone/tiny-rag/blob/main/src/common/prompt/load_prompt.py"
click node_node_tracing "https://github.com/refone/tiny-rag/blob/main/src/utils/node_utils.py"
click node_task_tracking "https://github.com/refone/tiny-rag/blob/main/src/utils/task_utils.py"
click node_logging "https://github.com/refone/tiny-rag/blob/main/src/utils/logging_utils.py"

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_import_graph,node_import_state,node_entry,node_pdf_convert,node_image_process,node_document_split,node_item_recognition,node_embedding,node_milvus_upsert,node_user toneBlue
class node_query_vectorize,node_retrieval,node_answer,node_milvus toneAmber
class node_vlm,node_minio_client,node_env_config,node_app_config,node_doc_type,node_prompt_loader toneMint
class node_node_tracing,node_task_tracking,node_logging toneRose
class node_mineru toneIndigo
```

## Components

### Document ingestion

- [Import workflow](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/main_graph.py): `src/processor/import_processor/main_graph.py`
- [Import state](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/state.py): `src/processor/import_processor/state.py`
- [File detection](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_entry.py): `src/processor/import_processor/nodes/node_entry.py`
- [PDF conversion](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_pdf_to_md.py): `src/processor/import_processor/nodes/node_pdf_to_md.py`
- [Image processing](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_md_img.py): `src/processor/import_processor/nodes/node_md_img.py`
- [Document splitting](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_document_split.py): `src/processor/import_processor/nodes/node_document_split.py`
- [Item recognition](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_item_name_recognize.py): `src/processor/import_processor/nodes/node_item_name_recognize.py`
- [Embedding](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_bge_embedding.py): `src/processor/import_processor/nodes/node_bge_embedding.py`
- [Vector persistence](https://github.com/refone/tiny-rag/blob/main/src/processor/import_processor/nodes/node_upsert_milvus.py): `src/processor/import_processor/nodes/node_upsert_milvus.py`

### Query answering

- [Query vectorization](https://github.com/refone/tiny-rag/tree/main/src/processor/query_processor): `src/processor/query_processor`
- [Three-way retrieval](https://github.com/refone/tiny-rag/tree/main/src/processor/query_processor): `src/processor/query_processor`
- [Answer generation](https://github.com/refone/tiny-rag/tree/main/src/processor/query_processor): `src/processor/query_processor`

### Shared services

- [Vision-language model](https://github.com/refone/tiny-rag/blob/main/src/common/model/vlm.py): `src/common/model/vlm.py`
- [Image object storage](https://github.com/refone/tiny-rag/blob/main/src/common/client/minio_client.py): `src/common/client/minio_client.py`
- [Environment config](https://github.com/refone/tiny-rag/blob/main/src/common/config/env_config.py): `src/common/config/env_config.py`
- [Application config](https://github.com/refone/tiny-rag/blob/main/src/common/config/app_config.py): `src/common/config/app_config.py`
- [Document types](https://github.com/refone/tiny-rag/blob/main/src/common/enum/doc_type.py): `src/common/enum/doc_type.py`
- [Prompt loading](https://github.com/refone/tiny-rag/blob/main/src/common/prompt/load_prompt.py): `src/common/prompt/load_prompt.py`

### Runtime infrastructure

- [Node tracing](https://github.com/refone/tiny-rag/blob/main/src/utils/node_utils.py): `src/utils/node_utils.py`
- [Task tracking](https://github.com/refone/tiny-rag/blob/main/src/utils/task_utils.py): `src/utils/task_utils.py`
- [Logging](https://github.com/refone/tiny-rag/blob/main/src/utils/logging_utils.py): `src/utils/logging_utils.py`

### Other components

- **Assistant user**
- **MinerU service**
- **Milvus**

## Connections

- Import workflow → File detection: dispatches first (evidence: `src/processor/import_processor/main_graph.py`)
- Import workflow → PDF conversion: routes PDFs (evidence: `src/processor/import_processor/main_graph.py`)
- Import workflow → Image processing: routes Markdown (evidence: `src/processor/import_processor/main_graph.py`)
- Import workflow → Document splitting: dispatches after images (evidence: `src/processor/import_processor/main_graph.py`)
- Import workflow → Item recognition: dispatches after split (evidence: `src/processor/import_processor/main_graph.py`)
- Import workflow → Embedding: dispatches after recognition (evidence: `src/processor/import_processor/main_graph.py`)
- Import workflow → Vector persistence: dispatches after embedding (evidence: `src/processor/import_processor/main_graph.py`)
- File detection → Import state: updates (evidence: `src/processor/import_processor/nodes/node_entry.py`)
- PDF conversion → MinerU service: uploads and polls (evidence: `src/processor/import_processor/nodes/node_pdf_to_md.py`)
- PDF conversion → Import state: writes Markdown path (evidence: `src/processor/import_processor/nodes/node_pdf_to_md.py`)
- Image processing → Vision-language model: requests image summaries (evidence: `src/processor/import_processor/nodes/node_md_img.py`)
- Image processing → Prompt loading: loads image prompt (evidence: `src/processor/import_processor/nodes/node_md_img.py`)
- Image processing → Image object storage: uploads images (evidence: `src/processor/import_processor/nodes/node_md_img.py`)
- Image processing → Application config: checks image formats (evidence: `src/processor/import_processor/nodes/node_md_img.py`)
- Image processing → Import state: reads and updates (evidence: `src/processor/import_processor/nodes/node_md_img.py`)
- Vector persistence → Milvus: persists vectors (evidence: `README.md`)
- Assistant user → Query vectorization: submits query (evidence: `README.md`)
- Query vectorization → Three-way retrieval: provides query vectors (evidence: `README.md`)
- Three-way retrieval → Milvus: retrieves matches (evidence: `README.md`)
- Three-way retrieval → Answer generation: provides retrieved context (evidence: `README.md`)
- Answer generation → Assistant user: returns answer (evidence: `README.md`)
- Vision-language model → Environment config: reads model settings (evidence: `src/common/model/vlm.py`)
- Image object storage → Environment config: reads storage settings (evidence: `src/common/client/minio_client.py`)
- File detection → Document types: detects file type (evidence: `src/processor/import_processor/nodes/node_entry.py`)
- Node tracing → Task tracking: records node status (evidence: `src/utils/node_utils.py`)
- Node tracing → Logging: logs node activity (evidence: `src/utils/node_utils.py`)
- Logging → Environment config: reads logging settings (evidence: `src/utils/logging_utils.py`)