# b0mbastik/messenger architecture

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

- Interactive diagram: https://gitdiagram.com/b0mbastik/messenger
- Repository: https://github.com/b0mbastik/messenger

## Overview

The repository contains two secure-messaging products: a TLS terminal client/server and a browser messenger with a FastAPI backend and React frontend. In the terminal flow, clients register or authenticate with a password and CA-backed identity, then exchange end-to-end encrypted direct messages through the server. The web version adds browser authentication, online presence, chat, settings, and persisted message history. The graph includes the shared cryptographic layer and each product’s major runtime stages. Some web UI and route wiring is unsampled, so uncertain links are dashed.

Main entry points: [`client/app.py`](https://github.com/b0mbastik/messenger/blob/main/client/app.py) (Terminal client), [`server/app.py`](https://github.com/b0mbastik/messenger/blob/main/server/app.py) (TLS server), [`web-messenger/frontend/src/app/MessengerApp.tsx`](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/app/MessengerApp.tsx) (Messenger interface), [`web-messenger/backend/app/api/routes.py`](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/api/routes.py) (HTTP and WS routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_terminal["Terminal Messenger"]
  node_terminal_client["Terminal client<br/>[app.py]"]
  node_terminal_server["TLS server<br/>[app.py]"]
  node_terminal_accounts[("Account registry<br/>[accounts.py]")]
  node_terminal_sessions[("Live sessions<br/>[storage.py]")]
end

subgraph group_shared["Shared Security"]
  node_tls["TLS setup<br/>[tls_utils.py]"]
  node_certs["CA certificates<br/>[cert_utils.py]"]
  node_identity["Local identity<br/>[identity.py]"]
  node_protocol["Message protocol<br/>[protocol.py]"]
  node_e2ee["E2E encryption<br/>[e2ee.py]"]
end

subgraph group_web_backend["Web Backend"]
  node_web_api["HTTP and WS routes<br/>[routes.py]"]
  node_web_accounts["Account workflows<br/>[accounts.py]"]
  node_web_security["Token security<br/>[security.py]"]
  node_web_store[("SQLite store<br/>[store.py]")]
  node_web_ws["WebSocket sessions<br/>[manager.py]"]
  node_web_schemas["Request schemas<br/>[schemas.py]"]
  node_web_runtime["Application setup<br/>[main.py]"]
end

subgraph group_web_frontend["Web Frontend"]
  node_web_ui["Messenger interface<br/>[MessengerApp.tsx]"]
  node_web_auth_ui["Authentication screens<br/>[LoginPage.tsx]"]
  node_web_chat_ui["Chat interface<br/>[ChatPanel.tsx]"]
  node_web_settings["Settings panel<br/>[SettingsPanel.tsx]"]
  node_web_crypto["Browser cryptography<br/>[e2ee.ts]"]
  node_web_identity_store["Browser identity storage<br/>[identityStore.ts]"]
  node_web_api_client["HTTP API client<br/>[api.ts]"]
  node_web_state["Chat and auth state<br/>[chatStore.ts]"]
end

node_terminal_user(("Messenger user"))
node_web_user(("Browser user"))

node_terminal_user -->|"uses"| node_terminal_client
node_terminal_client -->|"connects over TLS"| node_terminal_server
node_terminal_server -->|"authenticates accounts"| node_terminal_accounts
node_terminal_server -->|"tracks sessions"| node_terminal_sessions
node_terminal_server -->|"builds TLS context"| node_tls
node_terminal_client -->|"opens TLS connection"| node_tls
node_terminal_client -->|"checks certificates"| node_certs
node_terminal_server -->|"issues and verifies"| node_certs
node_terminal_client -->|"loads identity"| node_identity
node_terminal_client -->|"exchanges messages"| node_protocol
node_terminal_server -->|"reads messages"| node_protocol
node_terminal_client -->|"encrypts messages"| node_e2ee
node_terminal_server -->|"validates envelopes"| node_e2ee
node_web_user -.->|"uses"| node_web_ui
node_web_ui -.->|"presents auth"| node_web_auth_ui
node_web_ui -.->|"presents chat"| node_web_chat_ui
node_web_ui -.->|"presents settings"| node_web_settings
node_web_ui -.->|"uses state"| node_web_state
node_web_ui -.->|"requests API"| node_web_api_client
node_web_ui -.->|"encrypts messages"| node_web_crypto
node_web_crypto -.->|"uses identity"| node_web_identity_store
node_web_api_client -.->|"calls routes"| node_web_api
node_web_runtime -->|"registers routes"| node_web_api
node_web_runtime -->|"configures service"| node_web_accounts
node_web_runtime -->|"configures store"| node_web_store
node_web_runtime -->|"configures manager"| node_web_ws
node_web_api -->|"handles auth"| node_web_accounts
node_web_api -->|"checks identity"| node_web_security
node_web_api -->|"dispatches messages"| node_web_ws
node_web_api -->|"validates payloads"| node_web_schemas
node_web_accounts -->|"reads and writes"| node_web_store
node_web_accounts -->|"validates certificates"| node_certs

click node_terminal_client "https://github.com/b0mbastik/messenger/blob/main/client/app.py"
click node_terminal_server "https://github.com/b0mbastik/messenger/blob/main/server/app.py"
click node_terminal_accounts "https://github.com/b0mbastik/messenger/blob/main/server/accounts.py"
click node_terminal_sessions "https://github.com/b0mbastik/messenger/blob/main/server/storage.py"
click node_tls "https://github.com/b0mbastik/messenger/blob/main/ca/tls_utils.py"
click node_certs "https://github.com/b0mbastik/messenger/blob/main/ca/cert_utils.py"
click node_identity "https://github.com/b0mbastik/messenger/blob/main/shared/identity.py"
click node_protocol "https://github.com/b0mbastik/messenger/blob/main/shared/protocol.py"
click node_e2ee "https://github.com/b0mbastik/messenger/blob/main/shared/e2ee.py"
click node_web_ui "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/app/MessengerApp.tsx"
click node_web_auth_ui "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/features/auth/LoginPage.tsx"
click node_web_chat_ui "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/features/chats/ChatPanel.tsx"
click node_web_settings "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/features/settings/SettingsPanel.tsx"
click node_web_crypto "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/crypto/e2ee.ts"
click node_web_identity_store "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/crypto/identityStore.ts"
click node_web_api_client "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/lib/api.ts"
click node_web_state "https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/store/chatStore.ts"
click node_web_api "https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/api/routes.py"
click node_web_accounts "https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/services/accounts.py"
click node_web_security "https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/services/security.py"
click node_web_store "https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/services/store.py"
click node_web_ws "https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/ws/manager.py"
click node_web_schemas "https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/models/schemas.py"
click node_web_runtime "https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/main.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_terminal_client,node_terminal_server,node_terminal_accounts,node_terminal_sessions,node_terminal_user,node_web_user toneBlue
class node_tls,node_certs,node_identity,node_protocol,node_e2ee toneAmber
class node_web_api,node_web_accounts,node_web_security,node_web_store,node_web_ws,node_web_schemas,node_web_runtime toneMint
class node_web_ui,node_web_auth_ui,node_web_chat_ui,node_web_settings,node_web_crypto,node_web_identity_store,node_web_api_client,node_web_state toneRose
```

## Components

### Terminal Messenger

- [Terminal client](https://github.com/b0mbastik/messenger/blob/main/client/app.py): `client/app.py`
- [TLS server](https://github.com/b0mbastik/messenger/blob/main/server/app.py): `server/app.py`
- [Account registry](https://github.com/b0mbastik/messenger/blob/main/server/accounts.py): `server/accounts.py`
- [Live sessions](https://github.com/b0mbastik/messenger/blob/main/server/storage.py): `server/storage.py`

### Shared Security

- [TLS setup](https://github.com/b0mbastik/messenger/blob/main/ca/tls_utils.py): `ca/tls_utils.py`
- [CA certificates](https://github.com/b0mbastik/messenger/blob/main/ca/cert_utils.py): `ca/cert_utils.py`
- [Local identity](https://github.com/b0mbastik/messenger/blob/main/shared/identity.py): `shared/identity.py`
- [Message protocol](https://github.com/b0mbastik/messenger/blob/main/shared/protocol.py): `shared/protocol.py`
- [E2E encryption](https://github.com/b0mbastik/messenger/blob/main/shared/e2ee.py): `shared/e2ee.py`

### Web Backend

- [HTTP and WS routes](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/api/routes.py): `web-messenger/backend/app/api/routes.py`
- [Account workflows](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/services/accounts.py): `web-messenger/backend/app/services/accounts.py`
- [Token security](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/services/security.py): `web-messenger/backend/app/services/security.py`
- [SQLite store](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/services/store.py): `web-messenger/backend/app/services/store.py`
- [WebSocket sessions](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/ws/manager.py): `web-messenger/backend/app/ws/manager.py`
- [Request schemas](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/models/schemas.py): `web-messenger/backend/app/models/schemas.py`
- [Application setup](https://github.com/b0mbastik/messenger/blob/main/web-messenger/backend/app/main.py): `web-messenger/backend/app/main.py`

### Web Frontend

- [Messenger interface](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/app/MessengerApp.tsx): `web-messenger/frontend/src/app/MessengerApp.tsx`
- [Authentication screens](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/features/auth/LoginPage.tsx): `web-messenger/frontend/src/features/auth/LoginPage.tsx`
- [Chat interface](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/features/chats/ChatPanel.tsx): `web-messenger/frontend/src/features/chats/ChatPanel.tsx`
- [Settings panel](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/features/settings/SettingsPanel.tsx): `web-messenger/frontend/src/features/settings/SettingsPanel.tsx`
- [Browser cryptography](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/crypto/e2ee.ts): `web-messenger/frontend/src/crypto/e2ee.ts`
- [Browser identity storage](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/crypto/identityStore.ts): `web-messenger/frontend/src/crypto/identityStore.ts`
- [HTTP API client](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/lib/api.ts): `web-messenger/frontend/src/lib/api.ts`
- [Chat and auth state](https://github.com/b0mbastik/messenger/blob/main/web-messenger/frontend/src/store/chatStore.ts): `web-messenger/frontend/src/store/chatStore.ts`

### Other components

- **Messenger user**
- **Browser user**

## Connections

- Messenger user → Terminal client: uses (evidence: `README.md`)
- Terminal client → TLS server: connects over TLS (evidence: `README.md`)
- TLS server → Account registry: authenticates accounts (evidence: `server/app.py`)
- TLS server → Live sessions: tracks sessions (evidence: `server/app.py`)
- TLS server → TLS setup: builds TLS context (evidence: `server/app.py`)
- Terminal client → TLS setup: opens TLS connection (evidence: `client/app.py`)
- Terminal client → CA certificates: checks certificates (evidence: `client/app.py`)
- TLS server → CA certificates: issues and verifies (evidence: `server/app.py`)
- Terminal client → Local identity: loads identity (evidence: `client/app.py`)
- Terminal client → Message protocol: exchanges messages (evidence: `client/app.py`)
- TLS server → Message protocol: reads messages (evidence: `server/app.py`)
- Terminal client → E2E encryption: encrypts messages (evidence: `client/app.py`)
- TLS server → E2E encryption: validates envelopes (evidence: `server/app.py`)
- Browser user → Messenger interface: uses (evidence: `README.md`)
- Messenger interface → Authentication screens: presents auth
- Messenger interface → Chat interface: presents chat
- Messenger interface → Settings panel: presents settings
- Messenger interface → Chat and auth state: uses state
- Messenger interface → HTTP API client: requests API
- Messenger interface → Browser cryptography: encrypts messages (evidence: `README.md`)
- Browser cryptography → Browser identity storage: uses identity
- HTTP API client → HTTP and WS routes: calls routes
- Application setup → HTTP and WS routes: registers routes (evidence: `web-messenger/backend/app/main.py`)
- Application setup → Account workflows: configures service (evidence: `web-messenger/backend/app/main.py`)
- Application setup → SQLite store: configures store (evidence: `web-messenger/backend/app/main.py`)
- Application setup → WebSocket sessions: configures manager (evidence: `web-messenger/backend/app/main.py`)
- HTTP and WS routes → Account workflows: handles auth (evidence: `web-messenger/backend/app/api/routes.py`)
- HTTP and WS routes → Token security: checks identity (evidence: `web-messenger/backend/app/api/routes.py`)
- HTTP and WS routes → WebSocket sessions: dispatches messages (evidence: `web-messenger/backend/app/api/routes.py`)
- HTTP and WS routes → Request schemas: validates payloads (evidence: `web-messenger/backend/app/api/routes.py`)
- Account workflows → SQLite store: reads and writes (evidence: `web-messenger/backend/app/services/accounts.py`)
- Account workflows → CA certificates: validates certificates (evidence: `web-messenger/backend/app/services/accounts.py`)