# mhdamer06/chatmhat architecture

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

- Interactive diagram: https://gitdiagram.com/mhdamer06/chatmhat
- Repository: https://github.com/mhdamer06/chatmhat

## Overview

ChatMHAT is a local document-grounded chat application. Users upload supported files, which the API extracts and chunks, embeds with a local model, and stores with metadata in SQLite; upload progress is available over SSE. For chat, the API embeds the query, combines dense and BM25 rankings with reciprocal rank fusion, then streams a locally generated answer and source list. The README describes the browser UI and capabilities; its referenced frontend filename differs from the supplied tree, so the UI node uses the exact available path. Retrieval and model subsystems are represented where documented, with evidence limits reflected in edges.

Main entry points: [`main.py`](https://github.com/mhdamer06/chatmhat/blob/main/main.py) (FastAPI), [`index.html`](https://github.com/mhdamer06/chatmhat/blob/main/index.html) (Browser UI), [`db.py`](https://github.com/mhdamer06/chatmhat/blob/main/db.py) (SQLite store), [`document_processing.py`](https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py) (Format extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_ui["Browser UI<br/>[index.html]"]
end

subgraph group_api["API orchestration"]
  node_api_server["FastAPI<br/>[main.py]"]
  node_upload_sse["Upload progress SSE<br/>[main.py]"]
  node_answer_sse["Answer and sources SSE<br/>[main.py]"]
  node_document_api["Document management<br/>[main.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_file_extract["Format extraction"]
  node_chunking["Chunking"]
end

subgraph group_retrieval["Retrieval and inference"]
  node_embedding["Embedding model"]
  node_dense_search["Dense search"]
  node_bm25["BM25 search<br/>[main.py]"]
  node_fusion["RRF fusion"]
  node_chat_model["Chat model"]
end

subgraph group_storage["Persistence"]
  node_sqlite[("SQLite store<br/>[db.py]")]
end

node_user(("User"))

node_user -->|"uses"| node_ui
node_ui -->|"calls API"| node_api_server
node_api_server -->|"extracts file"| node_file_extract
node_file_extract -->|"chunks content"| node_chunking
node_api_server -->|"embeds batches"| node_embedding
node_api_server -->|"writes chunks"| node_sqlite
node_api_server -->|"streams progress"| node_upload_sse
node_api_server -->|"loads chunks"| node_sqlite
node_api_server -->|"ranks vectors"| node_dense_search
node_api_server -->|"queries index"| node_bm25
node_api_server -->|"fuses rankings"| node_fusion
node_api_server -->|"embeds query"| node_embedding
node_api_server -->|"streams completion"| node_chat_model
node_api_server -->|"streams answer"| node_answer_sse
node_api_server -->|"serves listing/deletion"| node_document_api
node_document_api -->|"reads and deletes"| node_sqlite
node_upload_sse -->|"reports progress"| node_ui
node_answer_sse -->|"returns sources"| node_ui

click node_ui "https://github.com/mhdamer06/chatmhat/blob/main/index.html"
click node_api_server "https://github.com/mhdamer06/chatmhat/blob/main/main.py"
click node_file_extract "https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py"
click node_chunking "https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py"
click node_dense_search "https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py"
click node_bm25 "https://github.com/mhdamer06/chatmhat/blob/main/main.py"
click node_fusion "https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py"
click node_sqlite "https://github.com/mhdamer06/chatmhat/blob/main/db.py"
click node_upload_sse "https://github.com/mhdamer06/chatmhat/blob/main/main.py"
click node_answer_sse "https://github.com/mhdamer06/chatmhat/blob/main/main.py"
click node_document_api "https://github.com/mhdamer06/chatmhat/blob/main/main.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_ui,node_user toneBlue
class node_api_server,node_upload_sse,node_answer_sse,node_document_api toneAmber
class node_file_extract,node_chunking toneMint
class node_embedding,node_dense_search,node_bm25,node_fusion,node_chat_model toneRose
class node_sqlite toneIndigo
```

## Components

### User interaction

- [Browser UI](https://github.com/mhdamer06/chatmhat/blob/main/index.html): `index.html`

### API orchestration

- [FastAPI](https://github.com/mhdamer06/chatmhat/blob/main/main.py): `main.py`
- [Upload progress SSE](https://github.com/mhdamer06/chatmhat/blob/main/main.py): `main.py`
- [Answer and sources SSE](https://github.com/mhdamer06/chatmhat/blob/main/main.py): `main.py`
- [Document management](https://github.com/mhdamer06/chatmhat/blob/main/main.py): `main.py`

### Document ingestion

- [Format extraction](https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py): `document_processing.py`
- [Chunking](https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py): `document_processing.py`

### Retrieval and inference

- **Embedding model**
- [Dense search](https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py): `document_processing.py`
- [BM25 search](https://github.com/mhdamer06/chatmhat/blob/main/main.py): `main.py`
- [RRF fusion](https://github.com/mhdamer06/chatmhat/blob/main/document_processing.py): `document_processing.py`
- **Chat model**

### Persistence

- [SQLite store](https://github.com/mhdamer06/chatmhat/blob/main/db.py): `db.py`

### Other components

- **User**

## Connections

- User → Browser UI: uses (evidence: `README.md`)
- Browser UI → FastAPI: calls API (evidence: `README.md`)
- FastAPI → Format extraction: extracts file (evidence: `main.py`)
- Format extraction → Chunking: chunks content (evidence: `document_processing.py`)
- FastAPI → Embedding model: embeds batches (evidence: `README.md`)
- FastAPI → SQLite store: writes chunks (evidence: `main.py`)
- FastAPI → Upload progress SSE: streams progress (evidence: `main.py`)
- FastAPI → SQLite store: loads chunks (evidence: `main.py`)
- FastAPI → Dense search: ranks vectors (evidence: `README.md`)
- FastAPI → BM25 search: queries index (evidence: `main.py`)
- FastAPI → RRF fusion: fuses rankings (evidence: `main.py`)
- FastAPI → Embedding model: embeds query (evidence: `README.md`)
- FastAPI → Chat model: streams completion (evidence: `main.py`)
- FastAPI → Answer and sources SSE: streams answer (evidence: `main.py`)
- FastAPI → Document management: serves listing/deletion (evidence: `main.py`)
- Document management → SQLite store: reads and deletes (evidence: `main.py`)
- Upload progress SSE → Browser UI: reports progress (evidence: `README.md`)
- Answer and sources SSE → Browser UI: returns sources (evidence: `README.md`)
