# marchbeta2087/mengxi-llm-chat architecture

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

- Interactive diagram: https://gitdiagram.com/marchbeta2087/mengxi-llm-chat
- Repository: https://github.com/marchbeta2087/mengxi-llm-chat

## Overview

Mengxi Chat is a self-hosted LLM chat application: users sign in, manage keys and plugins, chat with upstream models, and search encrypted conversation history; administrators manage users, quotas, plugins, and audit records. The Vue SPA calls a FastAPI API, which coordinates services, persistence, Redis-backed controls, cryptography, plugin isolation, and upstream requests. The README documents these capabilities, but several implementing modules were not excerpted, so their internal call paths are omitted rather than inferred.

Main entry points: [`src/backend/app/main.py`](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/main.py) (FastAPI application), [`src/backend/app/services/chat.py`](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/chat.py) (Chat orchestration), [`src/frontend/src/api/client.ts`](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/api/client.ts) (API client), [`src/backend/app/repositories/__init__.py`](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/repositories/__init__.py) (PostgreSQL data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_router["SPA routes<br/>[router.ts]"]
  node_authui["Session state<br/>[auth.ts]"]
  node_chatview["Chat interface<br/>[ChatView.vue]"]
  node_keyview["Key management UI<br/>[KeysView.vue]"]
  node_adminui["Admin interface<br/>[AdminView.vue]"]
  node_pluginsui["Plugin interface<br/>[PluginsView.vue]"]
  node_settingsui["Settings UI<br/>[SettingsView.vue]"]
  node_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and services"]
  node_entry["FastAPI application<br/>[main.py]"]
  node_authapi["Authentication routes<br/>[auth.py]"]
  node_chatapi["Chat and conversation routes<br/>[chat.py]"]
  node_keyapi["Key routes<br/>[keys.py]"]
  node_pluginapi["Plugin and admin routes<br/>[plugins.py]"]
  node_adminapi["Admin and audit routes<br/>[admin.py]"]
  node_authsvc["Authentication service<br/>[auth.py]"]
  node_chatsvc["Chat orchestration<br/>[chat.py]"]
  node_scheduler["Key pool scheduler<br/>[scheduler.py]"]
  node_ratelimit["Rate limits and quotas<br/>[ratelimit.py]"]
  node_limitsdomain["Limit rules<br/>[ratelimit.py]"]
  node_pluginsvc["Plugin policies<br/>[plugins.py]"]
end

subgraph group_security["Privacy and safety"]
  node_conversations["Encrypted conversations<br/>[conversation.py]"]
  node_keymanager["Key encryption manager<br/>[key_manager.py]"]
  node_crypto["Encryption primitives<br/>[cipher.py]"]
  node_kek["Master key provider<br/>[kek.py]"]
  node_blindindex["Blind-index search<br/>[blind_index.py]"]
  node_ssrf["SSRF validation<br/>[ssrf.py]"]
end

subgraph group_runtime["Runtime integrations"]
  node_sandbox["Plugin sandbox<br/>[sandbox.py]"]
  node_upstream["LLM upstream client<br/>[upstream.py]"]
  node_redis[("Redis counters<br/>[redis_store.py]")]
  node_database[("PostgreSQL data<br/>[__init__.py]")]
  node_models[("User and domain records<br/>[user.py]")]
end

node_browser(("User or admin"))
node_llm(("LLM provider"))
node_pluginprocess(("Plugin process"))

node_browser -->|"uses"| node_router
node_router -->|"checks session"| node_authui
node_authui -->|"requests auth"| node_client
node_browser -->|"chats"| node_chatview
node_chatview -->|"requests chat"| node_client
node_browser -->|"manages keys"| node_keyview
node_keyview -->|"requests keys"| node_client
node_browser -.->|"manages plugins"| node_pluginsui
node_pluginsui -.->|"requests plugins"| node_client
node_browser -.->|"administers"| node_adminui
node_adminui -.->|"requests admin"| node_client
node_browser -.->|"customizes"| node_settingsui
node_client -.->|"calls API"| node_entry
node_entry -->|"registers routes"| node_authapi
node_entry -->|"registers routes"| node_chatapi
node_entry -->|"registers routes"| node_keyapi
node_entry -->|"registers routes"| node_pluginapi
node_entry -->|"registers routes"| node_adminapi
node_authapi -->|"authenticates"| node_authsvc
node_authsvc -->|"uses repositories"| node_database
node_chatapi -.->|"dispatches chat"| node_chatsvc
node_chatsvc -.->|"stores messages"| node_conversations
node_chatsvc -.->|"selects key"| node_scheduler
node_chatsvc -.->|"checks limits"| node_ratelimit
node_chatsvc -.->|"applies plugins"| node_pluginsvc
node_chatsvc -.->|"sends requests"| node_upstream
node_upstream -.->|"calls provider"| node_llm
node_conversations -.->|"indexes search"| node_blindindex
node_conversations -.->|"gets conversation key"| node_keymanager
node_keymanager -->|"wraps keys"| node_kek
node_keymanager -->|"encrypts secrets"| node_crypto
node_conversations -.->|"persists conversations"| node_database
node_scheduler -.->|"loads key pool"| node_database
node_ratelimit -->|"uses rules"| node_limitsdomain
node_ratelimit -.->|"records counters"| node_redis
node_pluginsvc -.->|"runs plugins"| node_sandbox
node_sandbox -.->|"isolates execution"| node_pluginprocess
node_sandbox -->|"checks network access"| node_ssrf
node_ssrf -.->|"validates targets"| node_upstream
node_adminapi -.->|"reads admin records"| node_database
node_keyapi -.->|"manages key records"| node_database
node_database -->|"stores records"| node_models

click node_router "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/router.ts"
click node_authui "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/stores/auth.ts"
click node_chatview "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/ChatView.vue"
click node_keyview "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/KeysView.vue"
click node_adminui "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/AdminView.vue"
click node_pluginsui "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/PluginsView.vue"
click node_settingsui "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/SettingsView.vue"
click node_client "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/api/client.ts"
click node_entry "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/main.py"
click node_authapi "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/auth.py"
click node_chatapi "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/chat.py"
click node_keyapi "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/keys.py"
click node_pluginapi "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/plugins.py"
click node_adminapi "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/admin.py"
click node_authsvc "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/auth.py"
click node_chatsvc "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/chat.py"
click node_conversations "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/conversation.py"
click node_keymanager "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/key_manager.py"
click node_crypto "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/core/crypto/cipher.py"
click node_kek "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/core/crypto/kek.py"
click node_blindindex "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/domain/blind_index.py"
click node_scheduler "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/scheduler.py"
click node_ratelimit "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/ratelimit.py"
click node_limitsdomain "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/domain/ratelimit.py"
click node_pluginsvc "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/plugins.py"
click node_sandbox "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/infra/sandbox.py"
click node_ssrf "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/core/ssrf.py"
click node_upstream "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/infra/upstream.py"
click node_redis "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/infra/redis_store.py"
click node_database "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/repositories/__init__.py"
click node_models "https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/models/user.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_router,node_authui,node_chatview,node_keyview,node_adminui,node_pluginsui,node_settingsui,node_client,node_browser toneBlue
class node_entry,node_authapi,node_chatapi,node_keyapi,node_pluginapi,node_adminapi,node_authsvc,node_chatsvc,node_scheduler,node_ratelimit,node_limitsdomain,node_pluginsvc toneAmber
class node_conversations,node_keymanager,node_crypto,node_kek,node_blindindex,node_ssrf toneMint
class node_sandbox,node_upstream,node_redis,node_database,node_models toneRose
class node_llm,node_pluginprocess toneIndigo
```

## Components

### Web application

- [SPA routes](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/router.ts): `src/frontend/src/router.ts`
- [Session state](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/stores/auth.ts): `src/frontend/src/stores/auth.ts`
- [Chat interface](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/ChatView.vue): `src/frontend/src/views/ChatView.vue`
- [Key management UI](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/KeysView.vue): `src/frontend/src/views/KeysView.vue`
- [Admin interface](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/AdminView.vue): `src/frontend/src/views/AdminView.vue`
- [Plugin interface](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/PluginsView.vue): `src/frontend/src/views/PluginsView.vue`
- [Settings UI](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/views/SettingsView.vue): `src/frontend/src/views/SettingsView.vue`
- [API client](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/frontend/src/api/client.ts): `src/frontend/src/api/client.ts`

### API and services

- [FastAPI application](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/main.py): `src/backend/app/main.py`
- [Authentication routes](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/auth.py): `src/backend/app/api/auth.py`
- [Chat and conversation routes](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/chat.py): `src/backend/app/api/chat.py`
- [Key routes](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/keys.py): `src/backend/app/api/keys.py`
- [Plugin and admin routes](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/plugins.py): `src/backend/app/api/plugins.py`
- [Admin and audit routes](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/api/admin.py): `src/backend/app/api/admin.py`
- [Authentication service](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/auth.py): `src/backend/app/services/auth.py`
- [Chat orchestration](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/chat.py): `src/backend/app/services/chat.py`
- [Key pool scheduler](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/scheduler.py): `src/backend/app/services/scheduler.py`
- [Rate limits and quotas](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/ratelimit.py): `src/backend/app/services/ratelimit.py`
- [Limit rules](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/domain/ratelimit.py): `src/backend/app/domain/ratelimit.py`
- [Plugin policies](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/plugins.py): `src/backend/app/services/plugins.py`

### Privacy and safety

- [Encrypted conversations](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/conversation.py): `src/backend/app/services/conversation.py`
- [Key encryption manager](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/services/key_manager.py): `src/backend/app/services/key_manager.py`
- [Encryption primitives](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/core/crypto/cipher.py): `src/backend/app/core/crypto/cipher.py`
- [Master key provider](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/core/crypto/kek.py): `src/backend/app/core/crypto/kek.py`
- [Blind-index search](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/domain/blind_index.py): `src/backend/app/domain/blind_index.py`
- [SSRF validation](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/core/ssrf.py): `src/backend/app/core/ssrf.py`

### Runtime integrations

- [Plugin sandbox](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/infra/sandbox.py): `src/backend/app/infra/sandbox.py`
- [LLM upstream client](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/infra/upstream.py): `src/backend/app/infra/upstream.py`
- [Redis counters](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/infra/redis_store.py): `src/backend/app/infra/redis_store.py`
- [PostgreSQL data](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/repositories/__init__.py): `src/backend/app/repositories/__init__.py`
- [User and domain records](https://github.com/marchbeta2087/mengxi-llm-chat/blob/main/src/backend/app/models/user.py): `src/backend/app/models/user.py`

### Other components

- **User or admin**
- **LLM provider**
- **Plugin process**

## Connections

- User or admin → SPA routes: uses (evidence: `src/frontend/src/router.ts`)
- SPA routes → Session state: checks session (evidence: `src/frontend/src/router.ts`)
- Session state → API client: requests auth (evidence: `src/frontend/src/stores/auth.ts`)
- User or admin → Chat interface: chats (evidence: `src/frontend/src/views/ChatView.vue`)
- Chat interface → API client: requests chat (evidence: `src/frontend/src/views/ChatView.vue`)
- User or admin → Key management UI: manages keys (evidence: `src/frontend/src/views/KeysView.vue`)
- Key management UI → API client: requests keys (evidence: `src/frontend/src/views/KeysView.vue`)
- User or admin → Plugin interface: manages plugins
- Plugin interface → API client: requests plugins
- User or admin → Admin interface: administers
- Admin interface → API client: requests admin
- User or admin → Settings UI: customizes
- API client → FastAPI application: calls API
- FastAPI application → Authentication routes: registers routes (evidence: `src/backend/app/main.py`)
- FastAPI application → Chat and conversation routes: registers routes (evidence: `src/backend/app/main.py`)
- FastAPI application → Key routes: registers routes (evidence: `src/backend/app/main.py`)
- FastAPI application → Plugin and admin routes: registers routes (evidence: `src/backend/app/main.py`)
- FastAPI application → Admin and audit routes: registers routes (evidence: `src/backend/app/main.py`)
- Authentication routes → Authentication service: authenticates (evidence: `src/backend/app/api/auth.py`)
- Authentication service → PostgreSQL data: uses repositories (evidence: `src/backend/app/services/auth.py`)
- Chat and conversation routes → Chat orchestration: dispatches chat
- Chat orchestration → Encrypted conversations: stores messages
- Chat orchestration → Key pool scheduler: selects key
- Chat orchestration → Rate limits and quotas: checks limits
- Chat orchestration → Plugin policies: applies plugins
- Chat orchestration → LLM upstream client: sends requests
- LLM upstream client → LLM provider: calls provider
- Encrypted conversations → Blind-index search: indexes search
- Encrypted conversations → Key encryption manager: gets conversation key
- Key encryption manager → Master key provider: wraps keys (evidence: `src/backend/app/services/key_manager.py`)
- Key encryption manager → Encryption primitives: encrypts secrets (evidence: `src/backend/app/services/key_manager.py`)
- Encrypted conversations → PostgreSQL data: persists conversations
- Key pool scheduler → PostgreSQL data: loads key pool
- Rate limits and quotas → Limit rules: uses rules (evidence: `src/backend/app/api/deps.py`)
- Rate limits and quotas → Redis counters: records counters
- Plugin policies → Plugin sandbox: runs plugins
- Plugin sandbox → Plugin process: isolates execution
- Plugin sandbox → SSRF validation: checks network access (evidence: `src/backend/app/infra/sandbox.py`)
- SSRF validation → LLM upstream client: validates targets
- Admin and audit routes → PostgreSQL data: reads admin records
- Key routes → PostgreSQL data: manages key records
- PostgreSQL data → User and domain records: stores records (evidence: `src/backend/app/repositories/__init__.py`)
