# selfxplanatorium/lf-chat architecture

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

- Interactive diagram: https://gitdiagram.com/selfxplanatorium/lf-chat
- Repository: https://github.com/selfxplanatorium/lf-chat

## Overview

LF Chat is a self-hosted, multi-conversation assistant whose configurable n8n workflows provide the model and automation boundary. A user signs in, configures a webhook, sends a message with optional attachments, and follows the response in the active conversation over authenticated SSE. The graph includes documented account, settings, conversation-management, and backup capabilities. Some server routes and generation modules are unsampled; those relationships are shown only where the README or SOURCE INDEX supports them.

Main entry points: [`src/App.tsx`](https://github.com/selfxplanatorium/lf-chat/blob/master/src/App.tsx) (App shell), [`server/src/generation/manager.ts`](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/generation/manager.ts) (Generation manager), [`server/src/index.ts`](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/index.ts) (Express API routes), [`src/services/apiClient.ts`](https://github.com/selfxplanatorium/lf-chat/blob/master/src/services/apiClient.ts) (REST API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_thread["Chat thread"]
  node_conversation_ui["Conversation navigation<br/>[SidePanel.tsx]"]
  node_conversation_hook["Conversation state"]
  node_localization["Localization<br/>[translate.ts]"]
end

subgraph group_account["Accounts and settings"]
  node_auth_ui["Sign-in and registration<br/>[AuthPage.tsx]"]
  node_auth_state["Authentication state<br/>[useAuth.tsx]"]
  node_settings_ui["Settings and webhook setup<br/>[SettingsPage.tsx]"]
  node_settings_state["Settings state<br/>[useSettings.ts]"]
  node_backup["Import and export<br/>[DataSection.tsx]"]
end

subgraph group_server["API and orchestration"]
  node_api_client["REST API client<br/>[apiClient.ts]"]
  node_stream_client["SSE client<br/>[streamClient.ts]"]
  node_api_routes["Express API routes<br/>[index.ts]"]
  node_auth_routes["Auth endpoints<br/>[auth.ts]"]
  node_conversation_routes["Conversation endpoints<br/>[conversations.ts]"]
  node_generation["Generation manager<br/>[manager.ts]"]
  node_generation_events["SSE event bus<br/>[eventBus.ts]"]
end

subgraph group_storage["Persistence and files"]
  node_sqlite[("SQLite database<br/>[db.ts]")]
  node_attachments["Attachment handling<br/>[attachments.ts]"]
end

subgraph group_integration["Webhook integration"]
  node_webhook_runner["Webhook runner<br/>[runner.ts]"]
  node_n8n{{"Configured n8n workflow"}}
end

node_user(("Chat user"))

node_user -->|"uses"| node_app
node_app -->|"shows when signed out"| node_auth_ui
node_app -->|"renders active chat"| node_thread
node_app -->|"renders navigation"| node_conversation_ui
node_app -->|"uses conversation state"| node_conversation_hook
node_auth_ui -->|"signs in through"| node_auth_state
node_auth_state -->|"calls auth APIs"| node_api_client
node_app -->|"opens settings"| node_settings_ui
node_settings_ui -->|"edits settings"| node_settings_state
node_settings_state -->|"loads and saves"| node_api_client
node_settings_ui -->|"offers data management"| node_backup
node_conversation_hook -->|"loads and mutates chats"| node_api_client
node_conversation_hook -->|"subscribes to responses"| node_stream_client
node_api_client -->|"sends JSON requests"| node_api_routes
node_stream_client -->|"opens authenticated SSE"| node_api_routes
node_api_routes -->|"mounts routes"| node_auth_routes
node_api_routes -->|"mounts routes"| node_conversation_routes
node_auth_routes -->|"reads and writes accounts"| node_sqlite
node_conversation_routes -->|"reads and writes chats"| node_sqlite
node_conversation_routes -->|"starts chat generation"| node_generation
node_generation -->|"persists messages"| node_sqlite
node_generation -->|"resolves chat files"| node_attachments
node_generation -->|"runs generation"| node_webhook_runner
node_generation -->|"emits response events"| node_generation_events
node_webhook_runner -->|"posts webhook request"| node_n8n
node_generation_events -->|"streams response events"| node_stream_client
node_user -->|"uses translated interface"| node_localization
node_backup -.->|"backs up app data"| node_sqlite

click node_app "https://github.com/selfxplanatorium/lf-chat/blob/master/src/App.tsx"
click node_thread "https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/AssistantThread.tsx"
click node_conversation_ui "https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/SidePanel.tsx"
click node_conversation_hook "https://github.com/selfxplanatorium/lf-chat/blob/master/src/hooks/useConversations.ts"
click node_auth_ui "https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/AuthPage.tsx"
click node_auth_state "https://github.com/selfxplanatorium/lf-chat/blob/master/src/hooks/useAuth.tsx"
click node_settings_ui "https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/settings/SettingsPage.tsx"
click node_settings_state "https://github.com/selfxplanatorium/lf-chat/blob/master/src/hooks/useSettings.ts"
click node_backup "https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/settings/DataSection.tsx"
click node_api_client "https://github.com/selfxplanatorium/lf-chat/blob/master/src/services/apiClient.ts"
click node_stream_client "https://github.com/selfxplanatorium/lf-chat/blob/master/src/services/streamClient.ts"
click node_api_routes "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/index.ts"
click node_auth_routes "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/routes/auth.ts"
click node_conversation_routes "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/routes/conversations.ts"
click node_generation "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/generation/manager.ts"
click node_generation_events "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/generation/eventBus.ts"
click node_webhook_runner "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/generation/runner.ts"
click node_sqlite "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/db.ts"
click node_attachments "https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/lib/attachments.ts"
click node_localization "https://github.com/selfxplanatorium/lf-chat/blob/master/src/i18n/translate.ts"

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_app,node_thread,node_conversation_ui,node_conversation_hook,node_localization,node_user toneBlue
class node_auth_ui,node_auth_state,node_settings_ui,node_settings_state,node_backup toneAmber
class node_api_client,node_stream_client,node_api_routes,node_auth_routes,node_conversation_routes,node_generation,node_generation_events toneMint
class node_sqlite,node_attachments toneRose
class node_webhook_runner,node_n8n toneIndigo
```

## Components

### Chat experience

- [App shell](https://github.com/selfxplanatorium/lf-chat/blob/master/src/App.tsx): `src/App.tsx`
- [Chat thread](https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/AssistantThread.tsx): `src/components/AssistantThread.tsx`
- [Conversation navigation](https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/SidePanel.tsx): `src/components/SidePanel.tsx`
- [Conversation state](https://github.com/selfxplanatorium/lf-chat/blob/master/src/hooks/useConversations.ts): `src/hooks/useConversations.ts`
- [Localization](https://github.com/selfxplanatorium/lf-chat/blob/master/src/i18n/translate.ts): `src/i18n/translate.ts`

### Accounts and settings

- [Sign-in and registration](https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/AuthPage.tsx): `src/components/AuthPage.tsx`
- [Authentication state](https://github.com/selfxplanatorium/lf-chat/blob/master/src/hooks/useAuth.tsx): `src/hooks/useAuth.tsx`
- [Settings and webhook setup](https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/settings/SettingsPage.tsx): `src/components/settings/SettingsPage.tsx`
- [Settings state](https://github.com/selfxplanatorium/lf-chat/blob/master/src/hooks/useSettings.ts): `src/hooks/useSettings.ts`
- [Import and export](https://github.com/selfxplanatorium/lf-chat/blob/master/src/components/settings/DataSection.tsx): `src/components/settings/DataSection.tsx`

### API and orchestration

- [REST API client](https://github.com/selfxplanatorium/lf-chat/blob/master/src/services/apiClient.ts): `src/services/apiClient.ts`
- [SSE client](https://github.com/selfxplanatorium/lf-chat/blob/master/src/services/streamClient.ts): `src/services/streamClient.ts`
- [Express API routes](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/index.ts): `server/src/index.ts`
- [Auth endpoints](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/routes/auth.ts): `server/src/routes/auth.ts`
- [Conversation endpoints](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/routes/conversations.ts): `server/src/routes/conversations.ts`
- [Generation manager](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/generation/manager.ts): `server/src/generation/manager.ts`
- [SSE event bus](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/generation/eventBus.ts): `server/src/generation/eventBus.ts`

### Persistence and files

- [SQLite database](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/db.ts): `server/src/db.ts`
- [Attachment handling](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/lib/attachments.ts): `server/src/lib/attachments.ts`

### Webhook integration

- [Webhook runner](https://github.com/selfxplanatorium/lf-chat/blob/master/server/src/generation/runner.ts): `server/src/generation/runner.ts`
- **Configured n8n workflow**

### Other components

- **Chat user**

## Connections

- Chat user → App shell: uses (evidence: `README.md`)
- App shell → Sign-in and registration: shows when signed out (evidence: `src/App.tsx`)
- App shell → Chat thread: renders active chat (evidence: `src/App.tsx`)
- App shell → Conversation navigation: renders navigation (evidence: `src/App.tsx`)
- App shell → Conversation state: uses conversation state (evidence: `src/App.tsx`)
- Sign-in and registration → Authentication state: signs in through (evidence: `src/components/AuthPage.tsx`)
- Authentication state → REST API client: calls auth APIs (evidence: `src/hooks/useAuth.tsx`)
- App shell → Settings and webhook setup: opens settings (evidence: `src/App.tsx`)
- Settings and webhook setup → Settings state: edits settings (evidence: `src/components/settings/SettingsPage.tsx`)
- Settings state → REST API client: loads and saves (evidence: `src/hooks/useSettings.ts`)
- Settings and webhook setup → Import and export: offers data management (evidence: `src/components/settings/SettingsPage.tsx`)
- Conversation state → REST API client: loads and mutates chats (evidence: `src/hooks/useConversations.ts`)
- Conversation state → SSE client: subscribes to responses (evidence: `src/hooks/useConversations.ts`)
- REST API client → Express API routes: sends JSON requests (evidence: `README.md`)
- SSE client → Express API routes: opens authenticated SSE (evidence: `README.md`)
- Express API routes → Auth endpoints: mounts routes (evidence: `server/src/index.ts`)
- Express API routes → Conversation endpoints: mounts routes (evidence: `server/src/index.ts`)
- Auth endpoints → SQLite database: reads and writes accounts (evidence: `server/src/routes/auth.ts`)
- Conversation endpoints → SQLite database: reads and writes chats (evidence: `server/src/routes/conversations.ts`)
- Conversation endpoints → Generation manager: starts chat generation (evidence: `server/src/routes/conversations.ts`)
- Generation manager → SQLite database: persists messages (evidence: `server/src/generation/manager.ts`)
- Generation manager → Attachment handling: resolves chat files (evidence: `server/src/generation/manager.ts`)
- Generation manager → Webhook runner: runs generation (evidence: `server/src/generation/manager.ts`)
- Generation manager → SSE event bus: emits response events (evidence: `server/src/generation/manager.ts`)
- Webhook runner → Configured n8n workflow: posts webhook request (evidence: `README.md`)
- SSE event bus → SSE client: streams response events (evidence: `README.md`)
- Chat user → Localization: uses translated interface (evidence: `README.md`)
- Import and export → SQLite database: backs up app data
