# cam01h/manx-reg-rag architecture

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

- Interactive diagram: https://gitdiagram.com/cam01h/manx-reg-rag
- Repository: https://github.com/cam01h/manx-reg-rag

## Overview

manx-reg-rag is a retrieval-augmented Q&A application for Isle of Man AML/CFT legislation and guidance. A user submits a question through the web interface; the API restores conversation history, invokes an AI agent, and supplies retrieved passages and matched definitions so the answer can cite its sources. The documented preparation workflow converts source documents into structured chunks and definitions, then embeds and indexes them. The tree lacks the README-mentioned ingestion entry point, so preparation links show only supported stages; query wiring is based on sampled source.

Main entry points: [`extraction_ops/process_documents.py`](https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/process_documents.py) (Document processing), [`app/server.py`](https://github.com/cam01h/manx-reg-rag/blob/main/app/server.py) (FastAPI server), [`db_ops/retrieval.py`](https://github.com/cam01h/manx-reg-rag/blob/main/db_ops/retrieval.py) (Chunk retrieval), [`web/app.js`](https://github.com/cam01h/manx-reg-rag/blob/main/web/app.js) (Web client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_browser["Web client<br/>[app.js]"]
end

subgraph group_runtime["Question answering"]
  node_api["FastAPI server<br/>[server.py]"]
  node_sessions[("Session history<br/>[sessions.py]")]
  node_agent["Answer agent<br/>[llm.py]"]
end

subgraph group_knowledge["Knowledge preparation"]
  node_processing["Document processing"]
  node_pdf["PDF extraction<br/>[pdf_ops.py]"]
  node_markdown["Text normalization<br/>[md_ops.py]"]
  node_toolbelts["Document rules"]
  node_chunking["Section chunking<br/>[chunking.py]"]
  node_definitions["Definition extraction<br/>[definitions.py]"]
end

subgraph group_index["Retrieval index"]
  node_retrieval["Chunk retrieval<br/>[retrieval.py]"]
  node_qdrant[("Qdrant vector store")]
  node_embedding["Embedding and indexing<br/>[embed.py]"]
end

node_user(("Compliance user"))
node_model{{"OpenAI model"}}
node_source["Legislation and guidance"]
node_dense{{"Dense and sparse models"}}

node_user -->|"asks question"| node_browser
node_browser -->|"POST query"| node_api
node_api -->|"loads history"| node_sessions
node_sessions -->|"returns history"| node_api
node_api -->|"runs agent"| node_agent
node_agent -->|"generates answer"| node_model
node_agent -->|"calls tool"| node_retrieval
node_retrieval -->|"queries vectors"| node_qdrant
node_qdrant -->|"returns passages"| node_retrieval
node_retrieval -->|"returns passages and definitions"| node_agent
node_api -->|"saves turn"| node_sessions
node_api -->|"returns answer and citations"| node_browser
node_browser -->|"displays results"| node_user
node_source -.->|"provides documents"| node_processing
node_processing -->|"extracts PDF text"| node_pdf
node_processing -->|"normalizes text"| node_markdown
node_processing -->|"applies document rules"| node_toolbelts
node_processing -->|"creates chunks"| node_chunking
node_processing -->|"extracts definitions"| node_definitions
node_embedding -->|"embeds chunks"| node_dense
node_embedding -->|"writes vectors"| node_qdrant
node_retrieval -->|"embeds queries"| node_dense

click node_browser "https://github.com/cam01h/manx-reg-rag/blob/main/web/app.js"
click node_api "https://github.com/cam01h/manx-reg-rag/blob/main/app/server.py"
click node_sessions "https://github.com/cam01h/manx-reg-rag/blob/main/app/sessions.py"
click node_agent "https://github.com/cam01h/manx-reg-rag/blob/main/app/llm.py"
click node_retrieval "https://github.com/cam01h/manx-reg-rag/blob/main/db_ops/retrieval.py"
click node_processing "https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/process_documents.py"
click node_pdf "https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/pdf_ops.py"
click node_markdown "https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/md_ops.py"
click node_toolbelts "https://github.com/cam01h/manx-reg-rag/tree/main/extraction_ops/toolbelts"
click node_chunking "https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/chunking.py"
click node_definitions "https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/definitions.py"
click node_embedding "https://github.com/cam01h/manx-reg-rag/blob/main/db_ops/embed.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_browser,node_user toneBlue
class node_api,node_sessions,node_agent toneAmber
class node_processing,node_pdf,node_markdown,node_toolbelts,node_chunking,node_definitions toneMint
class node_retrieval,node_qdrant,node_embedding toneRose
class node_model,node_source,node_dense toneIndigo
```

## Components

### Web interface

- [Web client](https://github.com/cam01h/manx-reg-rag/blob/main/web/app.js): `web/app.js`

### Question answering

- [FastAPI server](https://github.com/cam01h/manx-reg-rag/blob/main/app/server.py): `app/server.py`
- [Session history](https://github.com/cam01h/manx-reg-rag/blob/main/app/sessions.py): `app/sessions.py`
- [Answer agent](https://github.com/cam01h/manx-reg-rag/blob/main/app/llm.py): `app/llm.py`

### Knowledge preparation

- [Document processing](https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/process_documents.py): `extraction_ops/process_documents.py`
- [PDF extraction](https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/pdf_ops.py): `extraction_ops/pdf_ops.py`
- [Text normalization](https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/md_ops.py): `extraction_ops/md_ops.py`
- [Document rules](https://github.com/cam01h/manx-reg-rag/tree/main/extraction_ops/toolbelts): `extraction_ops/toolbelts`
- [Section chunking](https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/chunking.py): `extraction_ops/chunking.py`
- [Definition extraction](https://github.com/cam01h/manx-reg-rag/blob/main/extraction_ops/definitions.py): `extraction_ops/definitions.py`

### Retrieval index

- [Chunk retrieval](https://github.com/cam01h/manx-reg-rag/blob/main/db_ops/retrieval.py): `db_ops/retrieval.py`
- **Qdrant vector store**
- [Embedding and indexing](https://github.com/cam01h/manx-reg-rag/blob/main/db_ops/embed.py): `db_ops/embed.py`

### Other components

- **Compliance user**
- **OpenAI model**
- **Legislation and guidance**
- **Dense and sparse models**

## Connections

- Compliance user → Web client: asks question
- Web client → FastAPI server: POST query
- FastAPI server → Session history: loads history
- Session history → FastAPI server: returns history
- FastAPI server → Answer agent: runs agent
- Answer agent → OpenAI model: generates answer
- Answer agent → Chunk retrieval: calls tool
- Chunk retrieval → Qdrant vector store: queries vectors
- Qdrant vector store → Chunk retrieval: returns passages
- Chunk retrieval → Answer agent: returns passages and definitions
- FastAPI server → Session history: saves turn
- FastAPI server → Web client: returns answer and citations
- Web client → Compliance user: displays results
- Legislation and guidance → Document processing: provides documents
- Document processing → PDF extraction: extracts PDF text
- Document processing → Text normalization: normalizes text
- Document processing → Document rules: applies document rules
- Document processing → Section chunking: creates chunks
- Document processing → Definition extraction: extracts definitions
- Embedding and indexing → Dense and sparse models: embeds chunks
- Embedding and indexing → Qdrant vector store: writes vectors
- Chunk retrieval → Dense and sparse models: embeds queries