# xsukax/xsukax-chatroom-e2e-system architecture

> Architecture diagram of the GitHub repository xsukax/xsukax-chatroom-e2e-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xsukax/xsukax-chatroom-e2e-system
- Repository: https://github.com/xsukax/xsukax-chatroom-e2e-system

## Overview

xsukax Chatroom is a browser-based, multi-room WebSocket chat system. Users connect through the HTML client, register with the Python server, then exchange room messages or use private messaging; the client encrypts private messages with RSA before the server forwards them. The server also manages rooms, presence, moderation, rate limits, and SQLite-backed room data. The README documents major features beyond the sampled server excerpts; those relationships are shown as documented, not as independently verified implementation details.

Main entry points: [`chat_server.py`](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py) (WebSocket server), [`chat_client.html`](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_client.html) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_client_ui["Chat interface<br/>[chat_client.html]"]
  node_client_crypto["Private-message crypto<br/>[chat_client.html]"]
end

subgraph group_runtime["Chat runtime"]
  node_server["WebSocket server<br/>[chat_server.py]"]
  node_registration["Registration and presence<br/>[chat_server.py]"]
  node_room_ops["Room management<br/>[chat_server.py]"]
  node_message_ops["Room messaging<br/>[chat_server.py]"]
  node_key_relay["Public-key relay<br/>[chat_server.py]"]
  node_private_forward["Private-message forwarding<br/>[chat_server.py]"]
  node_admin_ops["Administration and moderation<br/>[chat_server.py]"]
  node_flood_control["Flood protection<br/>[chat_server.py]"]
  node_heartbeat["Heartbeat handling<br/>[chat_server.py]"]
end

subgraph group_state["Persistence and security"]
  node_room_store[("Room database<br/>[chat_server.py]")]
  node_ban_store[("Ban records<br/>[chat_server.py]")]
end

node_users(("Chat users"))
node_admins(("Administrators"))

node_users -->|"use"| node_client_ui
node_admins -->|"use"| node_client_ui
node_client_ui -->|"connects by WebSocket"| node_server
node_server -->|"registers clients"| node_registration
node_registration -->|"loads user rooms"| node_room_ops
node_registration -->|"announces arrival"| node_message_ops
node_client_ui -->|"encrypts private messages"| node_client_crypto
node_client_crypto -->|"registers public key"| node_key_relay
node_server -->|"dispatches key registration"| node_key_relay
node_key_relay -->|"shares public keys"| node_client_crypto
node_client_ui -->|"sends room messages"| node_message_ops
node_server -->|"dispatches messages"| node_message_ops
node_client_ui -->|"sends encrypted messages"| node_private_forward
node_server -->|"routes private messages"| node_private_forward
node_private_forward -->|"forwards ciphertext"| node_client_ui
node_client_ui -->|"requests room actions"| node_room_ops
node_server -->|"dispatches room actions"| node_room_ops
node_admins -->|"issue admin commands"| node_admin_ops
node_server -->|"dispatches commands"| node_admin_ops
node_server -->|"limits message rate"| node_flood_control
node_server -->|"handles ping messages"| node_heartbeat
node_room_ops -->|"reads and writes rooms"| node_room_store
node_admin_ops -->|"persists IP bans"| node_ban_store

click node_client_ui "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_client.html"
click node_client_crypto "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_client.html"
click node_server "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_registration "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_room_ops "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_message_ops "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_key_relay "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_private_forward "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_admin_ops "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_flood_control "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_heartbeat "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_room_store "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py"
click node_ban_store "https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.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_client_ui,node_client_crypto,node_users toneBlue
class node_server,node_registration,node_room_ops,node_message_ops,node_key_relay,node_private_forward,node_admin_ops,node_flood_control,node_heartbeat toneAmber
class node_room_store,node_ban_store toneMint
class node_admins toneIndigo
```

## Components

### Browser client

- [Chat interface](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_client.html): `chat_client.html`
- [Private-message crypto](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_client.html): `chat_client.html`

### Chat runtime

- [WebSocket server](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Registration and presence](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Room management](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Room messaging](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Public-key relay](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Private-message forwarding](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Administration and moderation](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Flood protection](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Heartbeat handling](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`

### Persistence and security

- [Room database](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`
- [Ban records](https://github.com/xsukax/xsukax-chatroom-e2e-system/blob/main/chat_server.py): `chat_server.py`

### Other components

- **Chat users**
- **Administrators**

## Connections

- Chat users → Chat interface: use (evidence: `README.md`)
- Administrators → Chat interface: use (evidence: `README.md`)
- Chat interface → WebSocket server: connects by WebSocket (evidence: `README.md`)
- WebSocket server → Registration and presence: registers clients (evidence: `chat_server.py`)
- Registration and presence → Room management: loads user rooms (evidence: `chat_server.py`)
- Registration and presence → Room messaging: announces arrival (evidence: `chat_server.py`)
- Chat interface → Private-message crypto: encrypts private messages (evidence: `README.md`)
- Private-message crypto → Public-key relay: registers public key (evidence: `README.md`)
- WebSocket server → Public-key relay: dispatches key registration (evidence: `chat_server.py`)
- Public-key relay → Private-message crypto: shares public keys (evidence: `README.md`)
- Chat interface → Room messaging: sends room messages (evidence: `README.md`)
- WebSocket server → Room messaging: dispatches messages (evidence: `chat_server.py`)
- Chat interface → Private-message forwarding: sends encrypted messages (evidence: `README.md`)
- WebSocket server → Private-message forwarding: routes private messages (evidence: `README.md`)
- Private-message forwarding → Chat interface: forwards ciphertext (evidence: `README.md`)
- Chat interface → Room management: requests room actions (evidence: `README.md`)
- WebSocket server → Room management: dispatches room actions (evidence: `chat_server.py`)
- Administrators → Administration and moderation: issue admin commands (evidence: `README.md`)
- WebSocket server → Administration and moderation: dispatches commands (evidence: `README.md`)
- WebSocket server → Flood protection: limits message rate (evidence: `README.md`)
- WebSocket server → Heartbeat handling: handles ping messages (evidence: `chat_server.py`)
- Room management → Room database: reads and writes rooms (evidence: `chat_server.py`)
- Administration and moderation → Ban records: persists IP bans (evidence: `README.md`)
