# smarthtix-design/local-ai-chat-web-app architecture

> Architecture diagram of the GitHub repository smarthtix-design/local-ai-chat-web-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smarthtix-design/local-ai-chat-web-app
- Repository: https://github.com/smarthtix-design/local-ai-chat-web-app

## Overview

This is a local Ollama-backed web chat with optional document RAG and internet search. Users enter through the browser UI, send chat requests to the Python server, and receive streamed answers with retrieved sources when RAG is enabled. Administrators can manage settings, while documents are extracted, chunked, embedded, and indexed for later search. The graph preserves upload and URL-ingestion capabilities visible in the server excerpt. Some server internals are unsampled, so their links to dependencies are dashed where the excerpts do not establish the call.

Main entry points: [`server.py`](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py) (HTTP server), [`rag/ingest.py`](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/rag/ingest.py) (Document indexing), [`index.html`](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/index.html) (Chat interface), [`retrieval.py`](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/retrieval.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interfaces"]
  node_chatui["Chat interface<br/>[index.html]"]
  node_adminui["Admin interface<br/>[admin.html]"]
end

subgraph group_runtime["Chat server"]
  node_httpserver["HTTP server<br/>[server.py]"]
  node_chatflow["Chat and streaming<br/>[server.py]"]
  node_access["Access and rate limits<br/>[server.py]"]
  node_adminops["Admin controls<br/>[server.py]"]
  node_fileops["Uploads and URL intake<br/>[server.py]"]
  node_websearch["Web search<br/>[server.py]"]
  node_stats[("Usage and feedback<br/>[stats.py]")]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_ingest["Document indexing<br/>[ingest.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_webtools["Safe page extraction<br/>[webtools.py]"]
  node_chroma[("Persistent vectors")]
  node_documents["Shared documents"]
end

subgraph group_integrations["External services"]
  node_ollama["Ollama"]
  node_internet["Search providers"]
end

node_visitor(("Chat visitor"))

node_visitor -->|"uses"| node_chatui
node_chatui -->|"sends requests"| node_httpserver
node_adminui -->|"admin requests"| node_httpserver
node_httpserver -.->|"checks access"| node_access
node_httpserver -->|"routes chat"| node_chatflow
node_httpserver -->|"routes admin"| node_adminops
node_httpserver -->|"handles uploads"| node_fileops
node_chatflow -.->|"searches documents"| node_retrieval
node_chatflow -.->|"requests generation"| node_ollama
node_chatflow -->|"may search web"| node_websearch
node_websearch -->|"queries providers"| node_internet
node_websearch -.->|"fetches pages"| node_webtools
node_documents -->|"indexes files"| node_ingest
node_ingest -->|"extracts HTML"| node_webtools
node_ingest -->|"embeds chunks"| node_ollama
node_ingest -->|"writes vectors"| node_chroma
node_retrieval -.->|"searches vectors"| node_chroma
node_chatflow -.->|"logs usage"| node_stats

click node_chatui "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/index.html"
click node_adminui "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/admin.html"
click node_httpserver "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py"
click node_chatflow "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py"
click node_access "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py"
click node_adminops "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py"
click node_fileops "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py"
click node_websearch "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py"
click node_ingest "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/rag/ingest.py"
click node_retrieval "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/retrieval.py"
click node_webtools "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/webtools.py"
click node_chroma "https://github.com/smarthtix-design/local-ai-chat-web-app/tree/main/chroma_db"
click node_documents "https://github.com/smarthtix-design/local-ai-chat-web-app/tree/main/documents"
click node_stats "https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/stats.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_chatui,node_adminui toneBlue
class node_httpserver,node_chatflow,node_access,node_adminops,node_fileops,node_websearch,node_stats toneAmber
class node_ingest,node_retrieval,node_webtools,node_chroma,node_documents toneMint
class node_ollama,node_internet toneRose
class node_visitor toneIndigo
```

## Components

### Web interfaces

- [Chat interface](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/index.html): `index.html`
- [Admin interface](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/admin.html): `admin.html`

### Chat server

- [HTTP server](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py): `server.py`
- [Chat and streaming](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py): `server.py`
- [Access and rate limits](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py): `server.py`
- [Admin controls](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py): `server.py`
- [Uploads and URL intake](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py): `server.py`
- [Web search](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/server.py): `server.py`
- [Usage and feedback](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/stats.py): `stats.py`

### Knowledge retrieval

- [Document indexing](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/rag/ingest.py): `rag/ingest.py`
- [Hybrid retrieval](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/retrieval.py): `retrieval.py`
- [Safe page extraction](https://github.com/smarthtix-design/local-ai-chat-web-app/blob/main/webtools.py): `webtools.py`
- [Persistent vectors](https://github.com/smarthtix-design/local-ai-chat-web-app/tree/main/chroma_db): `chroma_db`
- [Shared documents](https://github.com/smarthtix-design/local-ai-chat-web-app/tree/main/documents): `documents`

### External services

- **Ollama**
- **Search providers**

### Other components

- **Chat visitor**

## Connections

- Chat visitor → Chat interface: uses (evidence: `README.txt`)
- Chat interface → HTTP server: sends requests (evidence: `README.txt`)
- Admin interface → HTTP server: admin requests (evidence: `server.py`)
- HTTP server → Access and rate limits: checks access (evidence: `server.py`)
- HTTP server → Chat and streaming: routes chat (evidence: `server.py`)
- HTTP server → Admin controls: routes admin (evidence: `server.py`)
- HTTP server → Uploads and URL intake: handles uploads (evidence: `server.py`)
- Chat and streaming → Hybrid retrieval: searches documents (evidence: `server.py`)
- Chat and streaming → Ollama: requests generation
- Chat and streaming → Web search: may search web (evidence: `server.py`)
- Web search → Search providers: queries providers (evidence: `server.py`)
- Web search → Safe page extraction: fetches pages (evidence: `server.py`)
- Shared documents → Document indexing: indexes files (evidence: `README.txt`)
- Document indexing → Safe page extraction: extracts HTML (evidence: `rag/ingest.py`)
- Document indexing → Ollama: embeds chunks (evidence: `rag/ingest.py`)
- Document indexing → Persistent vectors: writes vectors (evidence: `rag/ingest.py`)
- Hybrid retrieval → Persistent vectors: searches vectors
- Chat and streaming → Usage and feedback: logs usage (evidence: `server.py`)
