# brepublic/comp3334-project architecture

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

- Interactive diagram: https://gitdiagram.com/brepublic/comp3334-project
- Repository: https://github.com/brepublic/comp3334-project

## Overview

This is a CLI-based 1:1 E2EE messaging system: a client manages identity and conversations, encrypts and decrypts messages locally, and exchanges ciphertext through a server that handles accounts, contacts, and online or offline delivery. The server stores ciphertext rather than plaintext. The README documents key verification, replay protection, TTL cleanup, and encrypted delivery receipts; these are represented where the available source supports them. Some client and server workflows are only partially sampled, so the graph omits uncertain internal links.

Main entry points: [`Client/main.py`](https://github.com/brepublic/comp3334-project/blob/main/Client/main.py) (Client workflow), [`Server/Dependency.py`](https://github.com/brepublic/comp3334-project/blob/main/Server/Dependency.py) (Token validation), [`Server/MainServer.py`](https://github.com/brepublic/comp3334-project/blob/main/Server/MainServer.py) (Server app), [`Server/routers/ChatWS.py`](https://github.com/brepublic/comp3334-project/blob/main/Server/routers/ChatWS.py) (WebSocket relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Trusted client"]
  node_client_cli["Client workflow<br/>[main.py]"]
  node_client_api["HTTP API client<br/>[api.py]"]
  node_identity["Identity and E2EE<br/>[identity.py]"]
  node_client_ws["WebSocket client<br/>[ws_client.py]"]
  node_client_state["Session state<br/>[state.py]"]
end

subgraph group_server["Messaging service"]
  node_server_app["Server app<br/>[MainServer.py]"]
  node_registration["Registration<br/>[Register.py]"]
  node_authentication["Login and sessions<br/>[Login.py]"]
  node_contacts["Contacts and keys<br/>[Contacts.py]"]
  node_messages["Mailbox API<br/>[Message.py]"]
  node_chat_ws["WebSocket relay<br/>[ChatWS.py]"]
  node_ws_manager["Connection manager<br/>[ws_manager.py]"]
  node_auth_dependency["Token validation<br/>[Dependency.py]"]
end

subgraph group_storage["Local and server storage"]
  node_client_models[("Client data models<br/>[CLient_db.py]")]
  node_client_db_manager["Client DB manager<br/>[CdbManager.py]"]
  node_server_db_manager["Server DB manager<br/>[SdbManager.py]"]
  node_server_models[("Server data models<br/>[Server_db.py]")]
end

subgraph group_transport["Network transport"]
end

node_user(("CLI user"))
node_server(("Messaging server"))

node_user -->|"uses"| node_client_cli
node_client_cli -->|"calls"| node_client_api
node_client_cli -->|"uses"| node_identity
node_client_cli -->|"uses"| node_client_db_manager
node_client_cli -->|"uses"| node_client_state
node_client_cli -->|"receives via"| node_client_ws
node_identity -->|"uses"| node_client_db_manager
node_client_db_manager -->|"initializes"| node_client_models
node_client_api -->|"sends requests"| node_server
node_client_ws -->|"connects to"| node_chat_ws
node_server_app -->|"mounts"| node_registration
node_server_app -->|"mounts"| node_authentication
node_server_app -->|"mounts"| node_contacts
node_server_app -->|"mounts"| node_messages
node_server_app -->|"mounts"| node_chat_ws
node_registration -->|"uses"| node_auth_dependency
node_authentication -->|"uses"| node_auth_dependency
node_contacts -->|"uses"| node_auth_dependency
node_contacts -->|"queries"| node_server_models
node_messages -->|"uses"| node_auth_dependency
node_messages -->|"queries"| node_server_models
node_chat_ws -->|"validates tokens"| node_auth_dependency
node_chat_ws -->|"checks and stores"| node_server_models
node_chat_ws -->|"dispatches to"| node_ws_manager
node_auth_dependency -->|"gets sessions"| node_server_db_manager
node_server_db_manager -->|"initializes"| node_server_models
node_server -->|"returns responses"| node_client_api

click node_client_cli "https://github.com/brepublic/comp3334-project/blob/main/Client/main.py"
click node_client_api "https://github.com/brepublic/comp3334-project/blob/main/Client/api.py"
click node_identity "https://github.com/brepublic/comp3334-project/blob/main/Client/identity.py"
click node_client_ws "https://github.com/brepublic/comp3334-project/blob/main/Client/ws_client.py"
click node_client_state "https://github.com/brepublic/comp3334-project/blob/main/Client/state.py"
click node_client_models "https://github.com/brepublic/comp3334-project/blob/main/Client/CLient_db.py"
click node_client_db_manager "https://github.com/brepublic/comp3334-project/blob/main/Client/CdbManager.py"
click node_server_app "https://github.com/brepublic/comp3334-project/blob/main/Server/MainServer.py"
click node_registration "https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Register.py"
click node_authentication "https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Login.py"
click node_contacts "https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Contacts.py"
click node_messages "https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Message.py"
click node_chat_ws "https://github.com/brepublic/comp3334-project/blob/main/Server/routers/ChatWS.py"
click node_ws_manager "https://github.com/brepublic/comp3334-project/blob/main/Server/ws_manager.py"
click node_auth_dependency "https://github.com/brepublic/comp3334-project/blob/main/Server/Dependency.py"
click node_server_db_manager "https://github.com/brepublic/comp3334-project/blob/main/Server/SdbManager.py"
click node_server_models "https://github.com/brepublic/comp3334-project/blob/main/Server/Server_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_client_cli,node_client_api,node_identity,node_client_ws,node_client_state,node_user toneBlue
class node_server_app,node_registration,node_authentication,node_contacts,node_messages,node_chat_ws,node_ws_manager,node_auth_dependency toneAmber
class node_client_models,node_client_db_manager,node_server_db_manager,node_server_models,node_server toneMint
```

## Components

### Trusted client

- [Client workflow](https://github.com/brepublic/comp3334-project/blob/main/Client/main.py): `Client/main.py`
- [HTTP API client](https://github.com/brepublic/comp3334-project/blob/main/Client/api.py): `Client/api.py`
- [Identity and E2EE](https://github.com/brepublic/comp3334-project/blob/main/Client/identity.py): `Client/identity.py`
- [WebSocket client](https://github.com/brepublic/comp3334-project/blob/main/Client/ws_client.py): `Client/ws_client.py`
- [Session state](https://github.com/brepublic/comp3334-project/blob/main/Client/state.py): `Client/state.py`

### Messaging service

- [Server app](https://github.com/brepublic/comp3334-project/blob/main/Server/MainServer.py): `Server/MainServer.py`
- [Registration](https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Register.py): `Server/routers/Register.py`
- [Login and sessions](https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Login.py): `Server/routers/Login.py`
- [Contacts and keys](https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Contacts.py): `Server/routers/Contacts.py`
- [Mailbox API](https://github.com/brepublic/comp3334-project/blob/main/Server/routers/Message.py): `Server/routers/Message.py`
- [WebSocket relay](https://github.com/brepublic/comp3334-project/blob/main/Server/routers/ChatWS.py): `Server/routers/ChatWS.py`
- [Connection manager](https://github.com/brepublic/comp3334-project/blob/main/Server/ws_manager.py): `Server/ws_manager.py`
- [Token validation](https://github.com/brepublic/comp3334-project/blob/main/Server/Dependency.py): `Server/Dependency.py`

### Local and server storage

- [Client data models](https://github.com/brepublic/comp3334-project/blob/main/Client/CLient_db.py): `Client/CLient_db.py`
- [Client DB manager](https://github.com/brepublic/comp3334-project/blob/main/Client/CdbManager.py): `Client/CdbManager.py`
- [Server DB manager](https://github.com/brepublic/comp3334-project/blob/main/Server/SdbManager.py): `Server/SdbManager.py`
- [Server data models](https://github.com/brepublic/comp3334-project/blob/main/Server/Server_db.py): `Server/Server_db.py`

### Other components

- **CLI user**
- **Messaging server**

## Connections

- CLI user → Client workflow: uses (evidence: `README.md`)
- Client workflow → HTTP API client: calls (evidence: `Client/main.py`)
- Client workflow → Identity and E2EE: uses (evidence: `Client/main.py`)
- Client workflow → Client DB manager: uses (evidence: `Client/main.py`)
- Client workflow → Session state: uses (evidence: `Client/main.py`)
- Client workflow → WebSocket client: receives via (evidence: `Client/main.py`)
- Identity and E2EE → Client DB manager: uses (evidence: `Client/identity.py`)
- Client DB manager → Client data models: initializes (evidence: `Client/CdbManager.py`)
- HTTP API client → Messaging server: sends requests (evidence: `README.md`)
- WebSocket client → WebSocket relay: connects to (evidence: `README.md`)
- Server app → Registration: mounts (evidence: `Server/MainServer.py`)
- Server app → Login and sessions: mounts (evidence: `Server/MainServer.py`)
- Server app → Contacts and keys: mounts (evidence: `Server/MainServer.py`)
- Server app → Mailbox API: mounts (evidence: `Server/MainServer.py`)
- Server app → WebSocket relay: mounts (evidence: `Server/MainServer.py`)
- Registration → Token validation: uses (evidence: `Server/routers/Register.py`)
- Login and sessions → Token validation: uses (evidence: `Server/routers/Login.py`)
- Contacts and keys → Token validation: uses (evidence: `Server/routers/Contacts.py`)
- Contacts and keys → Server data models: queries (evidence: `Server/routers/Contacts.py`)
- Mailbox API → Token validation: uses (evidence: `Server/routers/Message.py`)
- Mailbox API → Server data models: queries (evidence: `Server/routers/Message.py`)
- WebSocket relay → Token validation: validates tokens (evidence: `Server/routers/ChatWS.py`)
- WebSocket relay → Server data models: checks and stores (evidence: `Server/routers/ChatWS.py`)
- WebSocket relay → Connection manager: dispatches to (evidence: `Server/routers/ChatWS.py`)
- Token validation → Server DB manager: gets sessions (evidence: `Server/Dependency.py`)
- Server DB manager → Server data models: initializes (evidence: `Server/SdbManager.py`)
- Messaging server → HTTP API client: returns responses (evidence: `README.md`)