# mingstar556/telegramcopy architecture

> Architecture diagram of the GitHub repository mingstar556/telegramcopy, 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/mingstar556/telegramcopy
- Repository: https://github.com/mingstar556/telegramcopy

## Overview

This is a self-hosted Telegram customer-support chat and bot-operator platform. An employee logs in to a bot-specific account, loads or syncs its conversations, and sends messages or media; the backend persists chat state and communicates with Telegram, while WebSockets provide live updates across devices. The frontend also provides private Saved Messages, AI chat summaries, session/account controls, audio tools, and theme settings. Several backend routes and frontend components are represented from the README and source index rather than inspected implementations, so those links are documented or omitted accordingly.

Main entry points: [`front-end/src/App.tsx`](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/App.tsx) (Application Shell), [`front-end/src/contexts/ChatContext.tsx`](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/ChatContext.tsx) (Conversation State), [`front-end/src/contexts/AuthContext.tsx`](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/AuthContext.tsx) (Authentication State), [`front-end/src/components/layout/ChatArea.tsx`](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/layout/ChatArea.tsx) (Chat Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Client"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_login["Login<br/>[LoginModal.tsx]"]
  node_chat_ui["Chat Interface<br/>[ChatArea.tsx]"]
  node_sidebar["Conversation Sidebar<br/>[Sidebar.tsx]"]
  node_chat_controls["Messaging Controls<br/>[ChatBar.tsx]"]
  node_messages["Message Rendering<br/>[MessageList.tsx]"]
  node_special["Saved Messages<br/>[SpecialView.tsx]"]
  node_summary["Chat Summary"]
  node_media_audio["Media and Audio<br/>[audioRecorder.ts]"]
  node_account_settings["Account Settings<br/>[SettingsModal.tsx]"]
end

subgraph group_state["Client State"]
  node_auth_state["Authentication State<br/>[AuthContext.tsx]"]
  node_chat_state["Conversation State<br/>[ChatContext.tsx]"]
  node_theme_state["Theme Settings<br/>[ThemeContext.tsx]"]
  node_api_client["REST API Client<br/>[api.ts]"]
  node_ws_client["WebSocket Client<br/>[websocket.ts]"]
end

subgraph group_backend["Django Backend"]
  node_api["Django REST Endpoints<br/>[views.py]"]
  node_realtime["WebSocket Consumer<br/>[consumers.py]"]
  node_ws_routes["WebSocket Routing<br/>[routing.py]"]
end

subgraph group_telegram["Telegram Integration"]
  node_bot_service["Bot Sync and Dispatch<br/>[bot_service.py]"]
end

subgraph group_persistence["Persistent Data"]
  node_data_models[("Chat and Account Records<br/>[models.py]")]
end

node_employee(("Employee"))
node_telegram_service["Telegram Bot API"]
node_summary_service["AI Summary Service"]

node_employee -->|"opens"| node_app
node_app -->|"checks auth"| node_auth_state
node_app -->|"reads chat state"| node_chat_state
node_app -->|"shows login"| node_login
node_app -->|"shows chat"| node_chat_ui
node_app -->|"shows conversations"| node_sidebar
node_app -->|"shows saved view"| node_special
node_login -->|"submits credentials"| node_auth_state
node_chat_ui -->|"renders"| node_chat_controls
node_chat_ui -->|"renders"| node_messages
node_chat_ui -.->|"opens summary"| node_summary
node_chat_controls -.->|"sends messages"| node_chat_state
node_chat_state -->|"reads account"| node_auth_state
node_chat_state -->|"loads and sends"| node_api_client
node_chat_state -->|"receives and sends"| node_ws_client
node_chat_state -->|"creates voice audio"| node_media_audio
node_auth_state -->|"authenticates"| node_api_client
node_auth_state -->|"connects session"| node_ws_client
node_account_settings -.->|"updates account"| node_auth_state
node_account_settings -.->|"updates preferences"| node_theme_state
node_special -->|"uses chat state"| node_chat_state
node_summary -.->|"requests summary"| node_summary_service
node_api_client -->|"calls REST endpoints"| node_api
node_ws_client -->|"opens socket"| node_ws_routes
node_ws_routes -->|"routes connection"| node_realtime
node_api -.->|"syncs and dispatches"| node_bot_service
node_bot_service -->|"polls and sends"| node_telegram_service
node_bot_service -->|"stores messages"| node_data_models
node_realtime -.->|"uses chat records"| node_data_models

click node_app "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/App.tsx"
click node_login "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/auth/LoginModal.tsx"
click node_chat_ui "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/layout/ChatArea.tsx"
click node_sidebar "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/layout/Sidebar.tsx"
click node_chat_controls "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/chat/ChatBar.tsx"
click node_messages "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/chat/MessageList.tsx"
click node_special "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/special/SpecialView.tsx"
click node_summary "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/chat/ChatSummaryModal.tsx"
click node_media_audio "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/services/audioRecorder.ts"
click node_account_settings "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/modals/SettingsModal.tsx"
click node_auth_state "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/AuthContext.tsx"
click node_chat_state "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/ChatContext.tsx"
click node_theme_state "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/ThemeContext.tsx"
click node_api_client "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/services/api.ts"
click node_ws_client "https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/services/websocket.ts"
click node_api "https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/views.py"
click node_realtime "https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/consumers.py"
click node_ws_routes "https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/routing.py"
click node_bot_service "https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/bot_service.py"
click node_data_models "https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/models.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_login,node_chat_ui,node_sidebar,node_chat_controls,node_messages,node_special,node_summary,node_media_audio,node_account_settings toneBlue
class node_auth_state,node_chat_state,node_theme_state,node_api_client,node_ws_client toneAmber
class node_api,node_realtime,node_ws_routes,node_telegram_service toneMint
class node_bot_service toneRose
class node_data_models,node_employee,node_summary_service toneIndigo
```

## Components

### Web Client

- [Application Shell](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/App.tsx): `front-end/src/App.tsx`
- [Login](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/auth/LoginModal.tsx): `front-end/src/components/auth/LoginModal.tsx`
- [Chat Interface](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/layout/ChatArea.tsx): `front-end/src/components/layout/ChatArea.tsx`
- [Conversation Sidebar](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/layout/Sidebar.tsx): `front-end/src/components/layout/Sidebar.tsx`
- [Messaging Controls](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/chat/ChatBar.tsx): `front-end/src/components/chat/ChatBar.tsx`
- [Message Rendering](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/chat/MessageList.tsx): `front-end/src/components/chat/MessageList.tsx`
- [Saved Messages](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/special/SpecialView.tsx): `front-end/src/components/special/SpecialView.tsx`
- [Chat Summary](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/chat/ChatSummaryModal.tsx): `front-end/src/components/chat/ChatSummaryModal.tsx`
- [Media and Audio](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/services/audioRecorder.ts): `front-end/src/services/audioRecorder.ts`
- [Account Settings](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/components/modals/SettingsModal.tsx): `front-end/src/components/modals/SettingsModal.tsx`

### Client State

- [Authentication State](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/AuthContext.tsx): `front-end/src/contexts/AuthContext.tsx`
- [Conversation State](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/ChatContext.tsx): `front-end/src/contexts/ChatContext.tsx`
- [Theme Settings](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/contexts/ThemeContext.tsx): `front-end/src/contexts/ThemeContext.tsx`
- [REST API Client](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/services/api.ts): `front-end/src/services/api.ts`
- [WebSocket Client](https://github.com/mingstar556/telegramcopy/blob/main/front-end/src/services/websocket.ts): `front-end/src/services/websocket.ts`

### Django Backend

- [Django REST Endpoints](https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/views.py): `backend/telegram_chat/views.py`
- [WebSocket Consumer](https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/consumers.py): `backend/telegram_chat/consumers.py`
- [WebSocket Routing](https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/routing.py): `backend/telegram_chat/routing.py`

### Telegram Integration

- [Bot Sync and Dispatch](https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/bot_service.py): `backend/telegram_chat/bot_service.py`

### Persistent Data

- [Chat and Account Records](https://github.com/mingstar556/telegramcopy/blob/main/backend/telegram_chat/models.py): `backend/telegram_chat/models.py`

### Other components

- **Employee**
- **Telegram Bot API**
- **AI Summary Service**

## Connections

- Employee → Application Shell: opens (evidence: `README.md`)
- Application Shell → Authentication State: checks auth (evidence: `front-end/src/App.tsx`)
- Application Shell → Conversation State: reads chat state (evidence: `front-end/src/App.tsx`)
- Application Shell → Login: shows login (evidence: `front-end/src/App.tsx`)
- Application Shell → Chat Interface: shows chat (evidence: `front-end/src/App.tsx`)
- Application Shell → Conversation Sidebar: shows conversations (evidence: `front-end/src/App.tsx`)
- Application Shell → Saved Messages: shows saved view (evidence: `front-end/src/App.tsx`)
- Login → Authentication State: submits credentials (evidence: `front-end/src/components/auth/LoginModal.tsx`)
- Chat Interface → Messaging Controls: renders (evidence: `front-end/src/components/layout/ChatArea.tsx`)
- Chat Interface → Message Rendering: renders (evidence: `front-end/src/components/layout/ChatArea.tsx`)
- Chat Interface → Chat Summary: opens summary (evidence: `README.md`)
- Messaging Controls → Conversation State: sends messages
- Conversation State → Authentication State: reads account (evidence: `front-end/src/contexts/ChatContext.tsx`)
- Conversation State → REST API Client: loads and sends (evidence: `front-end/src/contexts/ChatContext.tsx`)
- Conversation State → WebSocket Client: receives and sends (evidence: `front-end/src/contexts/ChatContext.tsx`)
- Conversation State → Media and Audio: creates voice audio (evidence: `front-end/src/contexts/ChatContext.tsx`)
- Authentication State → REST API Client: authenticates (evidence: `front-end/src/contexts/AuthContext.tsx`)
- Authentication State → WebSocket Client: connects session (evidence: `front-end/src/contexts/AuthContext.tsx`)
- Account Settings → Authentication State: updates account (evidence: `front-end/src/components/modals/SettingsModal.tsx`)
- Account Settings → Theme Settings: updates preferences (evidence: `front-end/src/components/modals/SettingsModal.tsx`)
- Saved Messages → Conversation State: uses chat state (evidence: `front-end/src/components/special/SpecialView.tsx`)
- Chat Summary → AI Summary Service: requests summary (evidence: `README.md`)
- REST API Client → Django REST Endpoints: calls REST endpoints (evidence: `README.md`)
- WebSocket Client → WebSocket Routing: opens socket (evidence: `README.md`)
- WebSocket Routing → WebSocket Consumer: routes connection (evidence: `backend/telegram_chat/routing.py`)
- Django REST Endpoints → Bot Sync and Dispatch: syncs and dispatches
- Bot Sync and Dispatch → Telegram Bot API: polls and sends (evidence: `backend/telegram_chat/bot_service.py`)
- Bot Sync and Dispatch → Chat and Account Records: stores messages (evidence: `backend/telegram_chat/bot_service.py`)
- WebSocket Consumer → Chat and Account Records: uses chat records (evidence: `backend/telegram_chat/consumers.py`)
