# yo-le-zz/anonymous architecture

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

- Interactive diagram: https://gitdiagram.com/yo-le-zz/anonymous
- Repository: https://github.com/yo-le-zz/anonymous

## Overview

Anonymous is a self-hostable, end-to-end encrypted group chat without accounts. The main workflow is: a person connects with the client, creates or joins a room using an out-of-band invitation, then sends encrypted messages or files that the server relays and stores as opaque data. The client also handles local secrets, room controls and live updates; the server supplies temporary sessions, access control, room and message APIs, and maintenance. README capabilities such as reactions, administration and public status are retained where evidence supports them; unsampled implementation details and uncertain links are omitted.

Main entry points: [`server/src/main.py`](https://github.com/yo-le-zz/anonymous/blob/main/server/src/main.py) (HTTP and live relay), [`client/src/main.py`](https://github.com/yo-le-zz/anonymous/blob/main/client/src/main.py) (Client workflow), [`server/src/retention.py`](https://github.com/yo-le-zz/anonymous/blob/main/server/src/retention.py) (Retention and upkeep), [`client/src/media.py`](https://github.com/yo-le-zz/anonymous/blob/main/client/src/media.py) (Encrypted files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_clientapp["Client workflow<br/>[main.py]"]
  node_clientconfig["Client preferences<br/>[config.py]"]
  node_clientstore[("Local room secrets<br/>[storage.py]")]
  node_payloads["Message payloads<br/>[protocol.py]"]
  node_framing["Stream framing<br/>[framing.py]"]
  node_media["Encrypted files<br/>[media.py]"]
end

subgraph group_server["Server"]
  node_serverapp["HTTP and live relay<br/>[main.py]"]
  node_serverprotocol["Envelope protocol<br/>[protocol.py]"]
  node_serverconfig["Server configuration<br/>[config.py]"]
  node_configwizard["Configuration assistant<br/>[config_wizard.py]"]
end

subgraph group_security["Security and policy"]
  node_cryptoproto["E2E encryption<br/>[crypto.py]"]
  node_sessions["Ephemeral sessions<br/>[session.py]"]
  node_auth["Server access tokens<br/>[auth.py]"]
  node_ratelimit["Progressive anti-spam<br/>[ratelimit.py]"]
  node_moderation["Content policy<br/>[moderation.py]"]
end

subgraph group_state["State and maintenance"]
  node_database[("Message and room store<br/>[database.py]")]
  node_filestore[("File storage<br/>[storage.py]")]
  node_retention["Retention and upkeep<br/>[retention.py]"]
end

node_user(("Chat participant"))

node_user -->|"uses"| node_clientapp
node_clientapp -->|"connects and exchanges"| node_serverapp
node_clientapp -->|"encrypts and decrypts"| node_cryptoproto
node_clientapp -->|"encodes payloads"| node_payloads
node_clientapp -->|"frames transfers"| node_framing
node_clientapp -->|"uploads and downloads"| node_media
node_media -->|"derives file keys"| node_cryptoproto
node_media -->|"uses file chunk size"| node_payloads
node_clientapp -->|"loads and saves rooms"| node_clientstore
node_clientapp -->|"reads preferences"| node_clientconfig
node_serverapp -->|"validates envelopes"| node_serverprotocol
node_serverapp -->|"reads and writes records"| node_database
node_serverapp -->|"stores and removes files"| node_filestore
node_serverapp -->|"registers and verifies sessions"| node_sessions
node_serverapp -->|"checks access"| node_auth
node_serverapp -->|"applies limits"| node_ratelimit
node_serverapp -->|"checks policy"| node_moderation
node_serverapp -->|"starts maintenance"| node_retention
node_serverapp -->|"loads configuration"| node_serverconfig
node_serverapp -->|"dispatches configuration"| node_configwizard
node_retention -->|"purges expired records"| node_database
node_retention -->|"deletes expired files"| node_filestore
node_retention -->|"cleans expired sessions"| node_sessions
node_retention -->|"sweeps counters"| node_ratelimit
node_retention -->|"reloads word policy"| node_moderation

click node_clientapp "https://github.com/yo-le-zz/anonymous/blob/main/client/src/main.py"
click node_clientconfig "https://github.com/yo-le-zz/anonymous/blob/main/client/src/config.py"
click node_clientstore "https://github.com/yo-le-zz/anonymous/blob/main/client/src/storage.py"
click node_cryptoproto "https://github.com/yo-le-zz/anonymous/blob/main/client/src/crypto.py"
click node_payloads "https://github.com/yo-le-zz/anonymous/blob/main/client/src/protocol.py"
click node_framing "https://github.com/yo-le-zz/anonymous/blob/main/client/src/framing.py"
click node_media "https://github.com/yo-le-zz/anonymous/blob/main/client/src/media.py"
click node_serverapp "https://github.com/yo-le-zz/anonymous/blob/main/server/src/main.py"
click node_serverprotocol "https://github.com/yo-le-zz/anonymous/blob/main/server/src/protocol.py"
click node_database "https://github.com/yo-le-zz/anonymous/blob/main/server/src/database.py"
click node_filestore "https://github.com/yo-le-zz/anonymous/blob/main/server/src/storage.py"
click node_sessions "https://github.com/yo-le-zz/anonymous/blob/main/server/src/session.py"
click node_auth "https://github.com/yo-le-zz/anonymous/blob/main/server/src/auth.py"
click node_ratelimit "https://github.com/yo-le-zz/anonymous/blob/main/server/src/ratelimit.py"
click node_moderation "https://github.com/yo-le-zz/anonymous/blob/main/server/src/moderation.py"
click node_retention "https://github.com/yo-le-zz/anonymous/blob/main/server/src/retention.py"
click node_serverconfig "https://github.com/yo-le-zz/anonymous/blob/main/server/src/config.py"
click node_configwizard "https://github.com/yo-le-zz/anonymous/blob/main/server/src/config_wizard.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_clientapp,node_clientconfig,node_clientstore,node_payloads,node_framing,node_media toneBlue
class node_serverapp,node_serverprotocol,node_serverconfig,node_configwizard toneAmber
class node_cryptoproto,node_sessions,node_auth,node_ratelimit,node_moderation toneMint
class node_database,node_filestore,node_retention toneRose
class node_user toneIndigo
```

## Components

### Client

- [Client workflow](https://github.com/yo-le-zz/anonymous/blob/main/client/src/main.py): `client/src/main.py`
- [Client preferences](https://github.com/yo-le-zz/anonymous/blob/main/client/src/config.py): `client/src/config.py`
- [Local room secrets](https://github.com/yo-le-zz/anonymous/blob/main/client/src/storage.py): `client/src/storage.py`
- [Message payloads](https://github.com/yo-le-zz/anonymous/blob/main/client/src/protocol.py): `client/src/protocol.py`
- [Stream framing](https://github.com/yo-le-zz/anonymous/blob/main/client/src/framing.py): `client/src/framing.py`
- [Encrypted files](https://github.com/yo-le-zz/anonymous/blob/main/client/src/media.py): `client/src/media.py`

### Server

- [HTTP and live relay](https://github.com/yo-le-zz/anonymous/blob/main/server/src/main.py): `server/src/main.py`
- [Envelope protocol](https://github.com/yo-le-zz/anonymous/blob/main/server/src/protocol.py): `server/src/protocol.py`
- [Server configuration](https://github.com/yo-le-zz/anonymous/blob/main/server/src/config.py): `server/src/config.py`
- [Configuration assistant](https://github.com/yo-le-zz/anonymous/blob/main/server/src/config_wizard.py): `server/src/config_wizard.py`

### Security and policy

- [E2E encryption](https://github.com/yo-le-zz/anonymous/blob/main/client/src/crypto.py): `client/src/crypto.py`
- [Ephemeral sessions](https://github.com/yo-le-zz/anonymous/blob/main/server/src/session.py): `server/src/session.py`
- [Server access tokens](https://github.com/yo-le-zz/anonymous/blob/main/server/src/auth.py): `server/src/auth.py`
- [Progressive anti-spam](https://github.com/yo-le-zz/anonymous/blob/main/server/src/ratelimit.py): `server/src/ratelimit.py`
- [Content policy](https://github.com/yo-le-zz/anonymous/blob/main/server/src/moderation.py): `server/src/moderation.py`

### State and maintenance

- [Message and room store](https://github.com/yo-le-zz/anonymous/blob/main/server/src/database.py): `server/src/database.py`
- [File storage](https://github.com/yo-le-zz/anonymous/blob/main/server/src/storage.py): `server/src/storage.py`
- [Retention and upkeep](https://github.com/yo-le-zz/anonymous/blob/main/server/src/retention.py): `server/src/retention.py`

### Other components

- **Chat participant**

## Connections

- Chat participant → Client workflow: uses (evidence: `README.md`)
- Client workflow → HTTP and live relay: connects and exchanges (evidence: `README.md`)
- Client workflow → E2E encryption: encrypts and decrypts (evidence: `client/src/main.py`)
- Client workflow → Message payloads: encodes payloads (evidence: `client/src/main.py`)
- Client workflow → Stream framing: frames transfers (evidence: `client/src/main.py`)
- Client workflow → Encrypted files: uploads and downloads (evidence: `client/src/main.py`)
- Encrypted files → E2E encryption: derives file keys (evidence: `client/src/media.py`)
- Encrypted files → Message payloads: uses file chunk size (evidence: `client/src/media.py`)
- Client workflow → Local room secrets: loads and saves rooms (evidence: `client/src/main.py`)
- Client workflow → Client preferences: reads preferences (evidence: `client/src/main.py`)
- HTTP and live relay → Envelope protocol: validates envelopes (evidence: `server/src/main.py`)
- HTTP and live relay → Message and room store: reads and writes records (evidence: `server/src/main.py`)
- HTTP and live relay → File storage: stores and removes files (evidence: `server/src/main.py`)
- HTTP and live relay → Ephemeral sessions: registers and verifies sessions (evidence: `server/src/main.py`)
- HTTP and live relay → Server access tokens: checks access (evidence: `server/src/main.py`)
- HTTP and live relay → Progressive anti-spam: applies limits (evidence: `server/src/main.py`)
- HTTP and live relay → Content policy: checks policy (evidence: `server/src/main.py`)
- HTTP and live relay → Retention and upkeep: starts maintenance (evidence: `server/src/main.py`)
- HTTP and live relay → Server configuration: loads configuration (evidence: `server/src/main.py`)
- HTTP and live relay → Configuration assistant: dispatches configuration (evidence: `server/src/main.py`)
- Retention and upkeep → Message and room store: purges expired records (evidence: `server/src/retention.py`)
- Retention and upkeep → File storage: deletes expired files (evidence: `server/src/retention.py`)
- Retention and upkeep → Ephemeral sessions: cleans expired sessions (evidence: `server/src/retention.py`)
- Retention and upkeep → Progressive anti-spam: sweeps counters (evidence: `server/src/retention.py`)
- Retention and upkeep → Content policy: reloads word policy (evidence: `server/src/retention.py`)
