# zeus22ru/wiki_4 architecture

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

- Interactive diagram: https://gitdiagram.com/zeus22ru/wiki_4
- Repository: https://github.com/zeus22ru/wiki_4

## Overview

This is a local-document knowledge base and RAG question-answering product, exposed through a web app, JSON API, CLI, and Telegram/Bitrix24 bots. The main path is document ingestion and indexing, then a user question through retrieval and local-model generation, with cited answers and chat history. The graph also preserves authentication, attachments, administration, and issue feedback. Edges follow explicit README or SOURCE INDEX references; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`web_app.py`](https://github.com/zeus22ru/wiki_4/blob/main/web_app.py) (Flask app), [`create_vector_db.py`](https://github.com/zeus22ru/wiki_4/blob/main/create_vector_db.py) (Document indexing), [`core/rag.py`](https://github.com/zeus22ru/wiki_4/blob/main/core/rag.py) (RAG orchestration), [`api/routes/admin.py`](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/admin.py) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Web access"]
  node_webapp["Flask app<br/>[web_app.py]"]
  node_auth_routes["Account routes<br/>[auth.py]"]
  node_auth_middleware["Session access<br/>[auth.py]"]
  node_chat_routes["Chat API<br/>[chat.py]"]
  node_document_routes["Document API<br/>[documents.py]"]
  node_issues_routes["Issue feedback API<br/>[issues.py]"]
end

subgraph group_knowledge["Knowledge and RAG"]
  node_indexer["Document indexing"]
  node_chunking["Text chunking<br/>[chunking.py]"]
  node_text_cleanup["HTML text extraction<br/>[html_text.py]"]
  node_manifest["Index manifest<br/>[index_manifest.py]"]
  node_rag["RAG orchestration<br/>[rag.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_embeddings["Model API client<br/>[embeddings.py]"]
  node_chroma[("ChromaDB index")]
end

subgraph group_chat["Chat and state"]
  node_attachments_api["Attachment routes"]
  node_attachments["Attachment storage"]
  node_history[("Chat history<br/>[chat_history.py]")]
end

subgraph group_integrations["External channels"]
  node_telegram_routes["Telegram API<br/>[telegram.py]"]
  node_telegram_worker["Telegram worker"]
  node_telegram_service["Telegram service<br/>[telegram.py]"]
  node_bitrix_worker["Bitrix worker"]
  node_bitrix_service["Bitrix integration<br/>[bitrix24.py]"]
end

subgraph group_operations["Administration"]
  node_admin_routes["Admin API<br/>[admin.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_overrides["Admin overrides"]
end

node_user(("Questioner"))
node_inference["Inference server"]
node_github["GitHub Issues"]

node_user -->|"asks via"| node_webapp
node_webapp -->|"registers routes"| node_chat_routes
node_webapp -->|"registers routes"| node_document_routes
node_webapp -->|"registers routes"| node_auth_routes
node_webapp -->|"registers routes"| node_issues_routes
node_auth_routes -->|"looks up users"| node_history
node_auth_middleware -->|"loads users"| node_history
node_document_routes -->|"invokes indexing"| node_indexer
node_indexer -->|"uses chunking"| node_chunking
node_indexer -->|"uses extraction"| node_text_cleanup
node_indexer -->|"uses manifest"| node_manifest
node_indexer -->|"requests vectors"| node_embeddings
node_indexer -->|"writes index"| node_chroma
node_chat_routes -->|"runs question answering"| node_rag
node_rag -->|"retrieves documents"| node_retrieval
node_retrieval -->|"embeds queries"| node_embeddings
node_retrieval -->|"queries index"| node_chroma
node_rag -->|"generates answers"| node_inference
node_embeddings -->|"calls model API"| node_inference
node_chat_routes -->|"saves messages"| node_history
node_chat_routes -->|"loads attachments"| node_attachments
node_webapp -->|"registers routes"| node_attachments_api
node_attachments_api -->|"uses storage"| node_attachments
node_rag -->|"enriches queries"| node_attachments
node_webapp -->|"registers routes"| node_admin_routes
node_admin_routes -->|"checks admin access"| node_auth_middleware
node_admin_routes -->|"manages chat data"| node_history
node_admin_routes -->|"uses retrieval"| node_retrieval
node_admin_routes -->|"manages overrides"| node_overrides
node_settings -->|"loads overrides"| node_overrides
node_issues_routes -->|"submits feedback"| node_github
node_telegram_worker -->|"uses service"| node_telegram_service
node_telegram_worker -.->|"uses chat runtime"| node_rag
node_telegram_worker -->|"uses attachments"| node_attachments
node_telegram_worker -.->|"calls internal API"| node_telegram_routes
node_telegram_routes -->|"manages linked chats"| node_history
node_bitrix_worker -->|"uses integration"| node_bitrix_service
node_bitrix_worker -.->|"answers questions"| node_rag

click node_webapp "https://github.com/zeus22ru/wiki_4/blob/main/web_app.py"
click node_auth_routes "https://github.com/zeus22ru/wiki_4/blob/main/api/routes/auth.py"
click node_auth_middleware "https://github.com/zeus22ru/wiki_4/blob/main/api/middleware/auth.py"
click node_chat_routes "https://github.com/zeus22ru/wiki_4/blob/main/api/routes/chat.py"
click node_document_routes "https://github.com/zeus22ru/wiki_4/blob/main/api/routes/documents.py"
click node_issues_routes "https://github.com/zeus22ru/wiki_4/blob/main/api/routes/issues.py"
click node_indexer "https://github.com/zeus22ru/wiki_4/blob/main/create_vector_db.py"
click node_chunking "https://github.com/zeus22ru/wiki_4/blob/main/core/chunking.py"
click node_text_cleanup "https://github.com/zeus22ru/wiki_4/blob/main/core/html_text.py"
click node_manifest "https://github.com/zeus22ru/wiki_4/blob/main/core/index_manifest.py"
click node_rag "https://github.com/zeus22ru/wiki_4/blob/main/core/rag.py"
click node_retrieval "https://github.com/zeus22ru/wiki_4/blob/main/core/retrieval.py"
click node_embeddings "https://github.com/zeus22ru/wiki_4/blob/main/utils/embeddings.py"
click node_attachments_api "https://github.com/zeus22ru/wiki_4/blob/main/api/routes/chat_attachments.py"
click node_attachments "https://github.com/zeus22ru/wiki_4/blob/main/core/chat_attachments.py"
click node_history "https://github.com/zeus22ru/wiki_4/blob/main/core/chat_history.py"
click node_telegram_routes "https://github.com/zeus22ru/wiki_4/blob/main/api/routes/telegram.py"
click node_telegram_worker "https://github.com/zeus22ru/wiki_4/blob/main/scripts/telegram_bot_worker.py"
click node_telegram_service "https://github.com/zeus22ru/wiki_4/blob/main/integrations/telegram.py"
click node_bitrix_worker "https://github.com/zeus22ru/wiki_4/blob/main/scripts/bitrix24_bot_worker.py"
click node_bitrix_service "https://github.com/zeus22ru/wiki_4/blob/main/integrations/bitrix24.py"
click node_admin_routes "https://github.com/zeus22ru/wiki_4/blob/main/api/routes/admin.py"
click node_settings "https://github.com/zeus22ru/wiki_4/blob/main/config/settings.py"
click node_overrides "https://github.com/zeus22ru/wiki_4/blob/main/config/runtime_overrides.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_webapp,node_auth_routes,node_auth_middleware,node_chat_routes,node_document_routes,node_issues_routes toneBlue
class node_indexer,node_chunking,node_text_cleanup,node_manifest,node_rag,node_retrieval,node_embeddings,node_chroma toneAmber
class node_attachments_api,node_attachments,node_history,node_inference toneMint
class node_telegram_routes,node_telegram_worker,node_telegram_service,node_bitrix_worker,node_bitrix_service toneRose
class node_admin_routes,node_settings,node_overrides,node_user,node_github toneIndigo
```

## Components

### Web access

- [Flask app](https://github.com/zeus22ru/wiki_4/blob/main/web_app.py): `web_app.py`
- [Account routes](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/auth.py): `api/routes/auth.py`
- [Session access](https://github.com/zeus22ru/wiki_4/blob/main/api/middleware/auth.py): `api/middleware/auth.py`
- [Chat API](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/chat.py): `api/routes/chat.py`
- [Document API](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/documents.py): `api/routes/documents.py`
- [Issue feedback API](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/issues.py): `api/routes/issues.py`

### Knowledge and RAG

- [Document indexing](https://github.com/zeus22ru/wiki_4/blob/main/create_vector_db.py): `create_vector_db.py`
- [Text chunking](https://github.com/zeus22ru/wiki_4/blob/main/core/chunking.py): `core/chunking.py`
- [HTML text extraction](https://github.com/zeus22ru/wiki_4/blob/main/core/html_text.py): `core/html_text.py`
- [Index manifest](https://github.com/zeus22ru/wiki_4/blob/main/core/index_manifest.py): `core/index_manifest.py`
- [RAG orchestration](https://github.com/zeus22ru/wiki_4/blob/main/core/rag.py): `core/rag.py`
- [Hybrid retrieval](https://github.com/zeus22ru/wiki_4/blob/main/core/retrieval.py): `core/retrieval.py`
- [Model API client](https://github.com/zeus22ru/wiki_4/blob/main/utils/embeddings.py): `utils/embeddings.py`
- **ChromaDB index**

### Chat and state

- [Attachment routes](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/chat_attachments.py): `api/routes/chat_attachments.py`
- [Attachment storage](https://github.com/zeus22ru/wiki_4/blob/main/core/chat_attachments.py): `core/chat_attachments.py`
- [Chat history](https://github.com/zeus22ru/wiki_4/blob/main/core/chat_history.py): `core/chat_history.py`

### External channels

- [Telegram API](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/telegram.py): `api/routes/telegram.py`
- [Telegram worker](https://github.com/zeus22ru/wiki_4/blob/main/scripts/telegram_bot_worker.py): `scripts/telegram_bot_worker.py`
- [Telegram service](https://github.com/zeus22ru/wiki_4/blob/main/integrations/telegram.py): `integrations/telegram.py`
- [Bitrix worker](https://github.com/zeus22ru/wiki_4/blob/main/scripts/bitrix24_bot_worker.py): `scripts/bitrix24_bot_worker.py`
- [Bitrix integration](https://github.com/zeus22ru/wiki_4/blob/main/integrations/bitrix24.py): `integrations/bitrix24.py`

### Administration

- [Admin API](https://github.com/zeus22ru/wiki_4/blob/main/api/routes/admin.py): `api/routes/admin.py`
- [Runtime settings](https://github.com/zeus22ru/wiki_4/blob/main/config/settings.py): `config/settings.py`
- [Admin overrides](https://github.com/zeus22ru/wiki_4/blob/main/config/runtime_overrides.py): `config/runtime_overrides.py`

### Other components

- **Questioner**
- **Inference server**
- **GitHub Issues**

## Connections

- Questioner → Flask app: asks via (evidence: `README.md`)
- Flask app → Chat API: registers routes (evidence: `web_app.py`)
- Flask app → Document API: registers routes (evidence: `web_app.py`)
- Flask app → Account routes: registers routes (evidence: `web_app.py`)
- Flask app → Issue feedback API: registers routes (evidence: `web_app.py`)
- Account routes → Chat history: looks up users (evidence: `api/routes/auth.py`)
- Session access → Chat history: loads users (evidence: `api/middleware/auth.py`)
- Document API → Document indexing: invokes indexing (evidence: `api/routes/documents.py`)
- Document indexing → Text chunking: uses chunking (evidence: `create_vector_db.py`)
- Document indexing → HTML text extraction: uses extraction (evidence: `create_vector_db.py`)
- Document indexing → Index manifest: uses manifest (evidence: `create_vector_db.py`)
- Document indexing → Model API client: requests vectors (evidence: `create_vector_db.py`)
- Document indexing → ChromaDB index: writes index (evidence: `README.md`)
- Chat API → RAG orchestration: runs question answering (evidence: `web_app.py`)
- RAG orchestration → Hybrid retrieval: retrieves documents (evidence: `core/rag.py`)
- Hybrid retrieval → Model API client: embeds queries (evidence: `core/retrieval.py`)
- Hybrid retrieval → ChromaDB index: queries index (evidence: `core/retrieval.py`)
- RAG orchestration → Inference server: generates answers
- Model API client → Inference server: calls model API (evidence: `utils/embeddings.py`)
- Chat API → Chat history: saves messages (evidence: `web_app.py`)
- Chat API → Attachment storage: loads attachments (evidence: `web_app.py`)
- Flask app → Attachment routes: registers routes (evidence: `web_app.py`)
- Attachment routes → Attachment storage: uses storage (evidence: `api/routes/chat_attachments.py`)
- RAG orchestration → Attachment storage: enriches queries (evidence: `core/rag.py`)
- Flask app → Admin API: registers routes (evidence: `web_app.py`)
- Admin API → Session access: checks admin access (evidence: `api/routes/admin.py`)
- Admin API → Chat history: manages chat data (evidence: `api/routes/admin.py`)
- Admin API → Hybrid retrieval: uses retrieval (evidence: `api/routes/admin.py`)
- Admin API → Admin overrides: manages overrides (evidence: `api/routes/admin.py`)
- Runtime settings → Admin overrides: loads overrides (evidence: `config/settings.py`)
- Issue feedback API → GitHub Issues: submits feedback (evidence: `api/routes/issues.py`)
- Telegram worker → Telegram service: uses service (evidence: `scripts/telegram_bot_worker.py`)
- Telegram worker → RAG orchestration: uses chat runtime
- Telegram worker → Attachment storage: uses attachments (evidence: `scripts/telegram_bot_worker.py`)
- Telegram worker → Telegram API: calls internal API
- Telegram API → Chat history: manages linked chats (evidence: `api/routes/telegram.py`)
- Bitrix worker → Bitrix integration: uses integration (evidence: `scripts/bitrix24_bot_worker.py`)
- Bitrix worker → RAG orchestration: answers questions
