# anish295/llm-chatbot-lyftr-ai architecture

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

- Interactive diagram: https://gitdiagram.com/anish295/llm-chatbot-lyftr-ai
- Repository: https://github.com/anish295/llm-chatbot-lyftr-ai

## Overview

Lyftr Chat is a React/FastAPI chatbot whose main workflow sends a session turn to the backend, rebuilds conversation context, obtains a cached or live LLM answer with key failover, and stores the successful exchange. The UI also restores history, exposes failure simulation and system-prompt settings, displays per-reply metadata, and supports export and themes. Backend request routing and service wiring are excerpted; several UI capabilities are documented or indexed but their full implementation was not sampled, so their internal links are limited to shown references.

Main entry points: [`frontend/src/App.tsx`](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/App.tsx) (Chat interface), [`backend/app/api.py`](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/api.py) (Chat endpoints), [`backend/app/config.py`](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/config.py) (Runtime settings), [`backend/app/llm_gateway.py`](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/llm_gateway.py) (LLM failover gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Chat experience"]
  node_app["Chat interface<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_reply_view["Reply display"]
  node_composer["Message composer<br/>[Composer.tsx]"]
  node_failure_ui["Failure simulator"]
  node_history_ui["Session restore<br/>[RestoreSession.tsx]"]
  node_settings_ui["Prompt settings"]
  node_theme["Theme control<br/>[theme.ts]"]
  node_export["Conversation export<br/>[export.ts]"]
end

subgraph group_api["Request handling"]
  node_backend_api["Chat endpoints<br/>[api.py]"]
  node_middleware["Request middleware<br/>[middleware.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_locks["Session ordering<br/>[session_locks.py]"]
end

subgraph group_inference["Inference and cache"]
  node_gateway["LLM failover gateway<br/>[llm_gateway.py]"]
  node_cache["Response cache<br/>[cache.py]"]
end

subgraph group_state["Session state"]
  node_database[("SQLite sessions<br/>[db.py]")]
end

node_user(("Chat user"))
node_provider["LLM provider"]

node_user -->|"uses"| node_app
node_app -->|"requests"| node_api_client
node_app -->|"renders"| node_reply_view
node_app -->|"renders"| node_composer
node_app -->|"renders"| node_failure_ui
node_app -->|"renders"| node_history_ui
node_app -->|"renders"| node_settings_ui
node_app -->|"uses"| node_theme
node_app -->|"uses"| node_export
node_api_client -->|"HTTP requests"| node_backend_api
node_backend_api -->|"reads and writes"| node_database
node_backend_api -->|"completes turn"| node_gateway
node_backend_api -->|"serializes session"| node_locks
node_backend_api -->|"reads settings"| node_config
node_gateway -->|"inference calls"| node_provider
node_gateway -->|"checks and stores"| node_cache
node_middleware -->|"wraps requests"| node_backend_api
node_config -->|"configures"| node_gateway
node_config -->|"selects path"| node_database
node_config -->|"configures"| node_cache

click node_app "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/api.ts"
click node_reply_view "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/AssistantMessage.tsx"
click node_composer "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/Composer.tsx"
click node_failure_ui "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/FailureSimulator.tsx"
click node_history_ui "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/RestoreSession.tsx"
click node_settings_ui "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/SystemPromptField.tsx"
click node_theme "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/theme.ts"
click node_export "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/export.ts"
click node_backend_api "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/api.py"
click node_middleware "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/middleware.py"
click node_config "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/config.py"
click node_locks "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/session_locks.py"
click node_gateway "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/llm_gateway.py"
click node_cache "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/cache.py"
click node_database "https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/db.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_app,node_api_client,node_reply_view,node_composer,node_failure_ui,node_history_ui,node_settings_ui,node_theme,node_export,node_user toneBlue
class node_backend_api,node_middleware,node_config,node_locks toneAmber
class node_gateway,node_cache toneMint
class node_database toneRose
class node_provider toneIndigo
```

## Components

### Chat experience

- [Chat interface](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Reply display](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/AssistantMessage.tsx): `frontend/src/components/AssistantMessage.tsx`
- [Message composer](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/Composer.tsx): `frontend/src/components/Composer.tsx`
- [Failure simulator](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/FailureSimulator.tsx): `frontend/src/components/FailureSimulator.tsx`
- [Session restore](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/RestoreSession.tsx): `frontend/src/components/RestoreSession.tsx`
- [Prompt settings](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/components/SystemPromptField.tsx): `frontend/src/components/SystemPromptField.tsx`
- [Theme control](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/theme.ts): `frontend/src/theme.ts`
- [Conversation export](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/frontend/src/export.ts): `frontend/src/export.ts`

### Request handling

- [Chat endpoints](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/api.py): `backend/app/api.py`
- [Request middleware](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/middleware.py): `backend/app/middleware.py`
- [Runtime settings](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/config.py): `backend/app/config.py`
- [Session ordering](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/session_locks.py): `backend/app/session_locks.py`

### Inference and cache

- [LLM failover gateway](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/llm_gateway.py): `backend/app/llm_gateway.py`
- [Response cache](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/cache.py): `backend/app/cache.py`

### Session state

- [SQLite sessions](https://github.com/anish295/llm-chatbot-lyftr-ai/blob/main/backend/app/db.py): `backend/app/db.py`

### Other components

- **Chat user**
- **LLM provider**

## Connections

- Chat user → Chat interface: uses (evidence: `README.md`)
- Chat interface → API client: requests (evidence: `frontend/src/App.tsx`)
- Chat interface → Reply display: renders (evidence: `frontend/src/App.tsx`)
- Chat interface → Message composer: renders (evidence: `frontend/src/App.tsx`)
- Chat interface → Failure simulator: renders (evidence: `frontend/src/App.tsx`)
- Chat interface → Session restore: renders (evidence: `frontend/src/App.tsx`)
- Chat interface → Prompt settings: renders (evidence: `frontend/src/App.tsx`)
- Chat interface → Theme control: uses (evidence: `frontend/src/App.tsx`)
- Chat interface → Conversation export: uses (evidence: `frontend/src/App.tsx`)
- API client → Chat endpoints: HTTP requests (evidence: `README.md`)
- Chat endpoints → SQLite sessions: reads and writes (evidence: `backend/app/api.py`)
- Chat endpoints → LLM failover gateway: completes turn (evidence: `backend/app/api.py`)
- Chat endpoints → Session ordering: serializes session (evidence: `backend/app/api.py`)
- Chat endpoints → Runtime settings: reads settings (evidence: `backend/app/api.py`)
- LLM failover gateway → LLM provider: inference calls (evidence: `README.md`)
- LLM failover gateway → Response cache: checks and stores (evidence: `README.md`)
- Request middleware → Chat endpoints: wraps requests (evidence: `backend/app/main.py`)
- Runtime settings → LLM failover gateway: configures (evidence: `backend/app/main.py`)
- Runtime settings → SQLite sessions: selects path (evidence: `backend/app/main.py`)
- Runtime settings → Response cache: configures (evidence: `backend/app/main.py`)
