# benzin8/wsnox architecture

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

- Interactive diagram: https://gitdiagram.com/benzin8/wsnox
- Repository: https://github.com/benzin8/wsnox

## Overview

#### Purpose and Runtime
WSNox is a same-origin messaging monolith: a FastAPI backend serves the built React SPA, REST APIs, and WebSockets. It runs Python 3.12/FastAPI with async SQLAlchemy, PostgreSQL 16, Redis 7, and React 18/Vite. Main backend composition is in `src/messenger/backend/app/main.py`; browser bootstrap and routing begin at `src/messenger/frontend_react/src/main.jsx` and `src/messenger/frontend_react/src/App.jsx`.

#### API, Identity, and Authorization
HTTP requests enter versioned routers for auth, chats, profiles, push, notifications, WebAuthn, and administration. Routers validate Pydantic request/response schemas, use auth dependencies, then delegate persistence to CRUD/services.
- API boundary: `src/messenger/backend/app/api_v1/routers/auth_router.py`, `src/messenger/backend/app/api_v1/routers/chat_router.py`, `src/messenger/backend/app/api_v1/auth/dependencies.py`
- Access JWT is short-lived and supplied in `Authorization`; refresh JWT is an httpOnly per-user cookie. Password hashing, token work, rate limiting, and RBAC gates belong in `src/messenger/backend/core/security.py`, `src/messenger/backend/core/rate_limit.py`, and `src/messenger/backend/core/permissions.py`.

#### Persistence and Domain Model
PostgreSQL is the source of truth, accessed through async session/base setup and Alembic migrations. Core entities cover users/profiles, chats and membership, encrypted messages, reactions/read receipts, blocks/mutes, push subscriptions, WebAuthn credentials, and role audit history.
- Database boundary: `src/messenger/backend/db/session.py`, `src/messenger/backend/db/base.py`, `alembic/versions/10a062ee954a_initial_tables.py`
- Messaging model and data access: `src/messenger/backend/models/chat.py`, `src/messenger/backend/models/message.py`, `src/messenger/backend/crud/message.py`.

#### Chat Delivery and Realtime State
The browser chat screen uses hooks to establish a WebSocket and issue chat actions. WebSocket authentication occurs via the first JWT-bearing message. The server maintains multiple sockets per user, publishes events through Redis Pub/Sub for multi-worker delivery, and tracks transient presence, active-chat viewing, and ephemeral events in Redis/TTL state.
- Backend realtime boundary: `src/messenger/backend/app/ws/router.py`, `src/messenger/backend/app/ws/presence.py`, `src/messenger/backend/app/ws/viewing_chat.py`
- Client integration: `src/messenger/frontend_react/src/hooks/useChatSocket.js`, `src/messenger/frontend_react/src/pages/chat/ChatPage.jsx`.

#### Message and Media Pipeline
Messages are persisted encrypted with AES-GCM and decrypted server-side for authorized delivery/search. Chat routes/CRUD apply membership, consent, block, channel, moderation, reaction, and read-receipt rules. Media uploads are processed by type: images resized and stripped of EXIF, video/audio metadata removed, ordinary files retained; objects are stored externally and exposed with presigned URLs.
- Crypto and message flow: `src/messenger/backend/core/crypto.py`, `src/messenger/backend/crud/chat.py`, `src/messenger/backend/crud/message.py`
- Storage/media boundary: `src/messenger/backend/services/media.py`, `src/messenger/backend/services/storage.py`, `src/messenger/backend/services/avatar.py`.

#### Frontend Product Shell
React owns landing, authentication, chat, profile, admin/dashboard, and channel-join views. Chat UI composes list/window/message/attachment and album components; stateful hooks bridge REST and WebSocket events. Account refresh interception enables multi-account switching without exposing refresh tokens to JS.
- Primary UI: `src/messenger/frontend_react/src/pages/chat/ChatPage.jsx`, `src/messenger/frontend_react/src/components/chat/ChatWindow.jsx`, `src/messenger/frontend_react/src/features/accounts/refreshInterceptor.js`
- Admin/RBAC UI: `src/messenger/frontend_react/src/pages/DashboardPage.jsx`, `src/messenger/frontend_react/src/components/AdminRoute.jsx`.

#### Notifications and External Integrations
Redis also supports caching, rate limits, unread/presence state, and Pub/Sub. Web Push uses VAPID subscriptions, while the PWA service worker receives pushes; active-chat, mute, and DND filtering determine notification delivery. Object storage is S3-compatible (documented as Yandex S3), and optional SMTP supports email verification/reset.
- Push pipeline: `src/messenger/backend/app/ws/push.py`, `src/messenger/backend/crud/push_subscription.py`, `src/messenger/frontend_react/public/sw.js`
- Redis abstraction: `src/messenger/backend/core/redis.py`, `src/messenger/backend/core/cache.py`.

#### Deployment Boundary
Docker Compose provisions application, PostgreSQL, and Redis; Nginx fronts production/static/WebSocket traffic. Startup is containerized via `Dockerfile` and `entrypoint.sh`; CI builds/tests and deployment publishes to GHCR then deploys over SSH.
- Infrastructure: `docker-compose.yml`, `docker-compose.prod.yml`, `nginx/wsnox.conf`
- Schema evolution and delivery: `alembic/env.py`, `.github/workflows/deploy.yml`.

Main entry points: [`src/messenger/backend/app/api_v1/routers/chat_router.py`](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/api_v1/routers/chat_router.py) (Versioned REST routers), [`src/messenger/backend/app/ws/router.py`](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/ws/router.py) (Realtime gateway), [`src/messenger/backend/app/main.py`](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/main.py) (FastAPI composition), [`src/messenger/frontend_react/src/hooks/useChatSocket.js`](https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/hooks/useChatSocket.js) (Chat socket hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser SPA"]
  node_spa_bootstrap["React app and routes<br/>React SPA<br/>[App.jsx]"]
  node_chat_ui["Chat UI<br/>React page<br/>[ChatPage.jsx]"]
  node_socket_hook["Chat socket hook<br/>WebSocket client<br/>[useChatSocket.js]"]
  node_refresh_interceptor["Account refresh<br/>HTTP interceptor"]
  node_service_worker["PWA push receiver<br/>Service worker<br/>[sw.js]"]
end

subgraph group_backend["FastAPI application"]
  node_app{{"FastAPI composition<br/>ASGI application<br/>[main.py]"}}
  node_api_routers["Versioned REST routers<br/>API boundary<br/>[chat_router.py]"]
  node_authz["Identity and RBAC<br/>auth dependencies<br/>[dependencies.py]"]
  node_security["Security controls<br/>security service<br/>[security.py]"]
  node_message_domain["Chat and message domain<br/>CRUD layer"]
  node_crypto["Message encryption<br/>AES-GCM service<br/>[crypto.py]"]
  node_ws_router{{"Realtime gateway<br/>WebSocket router<br/>[router.py]"}}
  node_presence["Presence and active chat<br/>realtime state<br/>[presence.py]"]
  node_media["Media pipeline<br/>media service<br/>[media.py]"]
end

subgraph group_state["Data and realtime state"]
  node_postgres[("PostgreSQL<br/>source-of-truth database<br/>[session.py]")]
  node_migrations["Alembic migrations<br/>schema evolution<br/>[env.py]"]
  node_redis[("Redis<br/>cache and Pub/Sub<br/>[redis.py]")]
end

subgraph group_integrations["External delivery"]
  node_object_storage[("S3-compatible storage<br/>object storage<br/>[storage.py]")]
  node_push["Web Push delivery<br/>push service<br/>[push.py]"]
end

subgraph group_ops["Deployment"]
  node_edge["Nginx and Compose<br/>production edge<br/>[wsnox.conf]"]
end

node_spa_bootstrap -->|"same-origin HTTP"| node_app
node_chat_ui -->|"uses"| node_socket_hook
node_socket_hook -->|"WebSocket actions/events"| node_ws_router
node_refresh_interceptor -->|"refreshes session"| node_api_routers
node_app -->|"mounts"| node_api_routers
node_app -->|"mounts"| node_ws_router
node_api_routers -->|"auth dependency"| node_authz
node_authz -->|"JWT and RBAC"| node_security
node_api_routers -->|"chat commands"| node_message_domain
node_message_domain -->|"encrypt/decrypt"| node_crypto
node_message_domain -->|"persists domain data"| node_postgres
node_ws_router -->|"realtime chat actions"| node_message_domain
node_ws_router -->|"updates"| node_presence
node_ws_router -->|"publishes and subscribes"| node_redis
node_presence -->|"TTL state"| node_redis
node_api_routers -->|"uploads"| node_media
node_media -->|"stores objects"| node_object_storage
node_api_routers -->|"subscription and notification flow"| node_push
node_push -->|"VAPID push"| node_service_worker
node_migrations -->|"evolves schema"| node_postgres
node_edge -->|"proxies API and WebSockets"| node_app

click node_spa_bootstrap "https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/App.jsx"
click node_chat_ui "https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/pages/chat/ChatPage.jsx"
click node_socket_hook "https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/hooks/useChatSocket.js"
click node_refresh_interceptor "https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/features/accounts/refreshInterceptor.js"
click node_service_worker "https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/public/sw.js"
click node_app "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/main.py"
click node_api_routers "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/api_v1/routers/chat_router.py"
click node_authz "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/api_v1/auth/dependencies.py"
click node_security "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/core/security.py"
click node_crypto "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/core/crypto.py"
click node_ws_router "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/ws/router.py"
click node_presence "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/ws/presence.py"
click node_media "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/services/media.py"
click node_postgres "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/db/session.py"
click node_migrations "https://github.com/benzin8/wsnox/blob/main/alembic/env.py"
click node_redis "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/core/redis.py"
click node_object_storage "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/services/storage.py"
click node_push "https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/ws/push.py"
click node_edge "https://github.com/benzin8/wsnox/blob/main/nginx/wsnox.conf"

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_spa_bootstrap,node_chat_ui,node_socket_hook,node_refresh_interceptor,node_service_worker toneBlue
class node_app,node_api_routers,node_authz,node_security,node_message_domain,node_crypto,node_ws_router,node_presence,node_media toneAmber
class node_postgres,node_migrations,node_redis toneMint
class node_object_storage,node_push toneRose
class node_edge toneIndigo
```

## Components

### Browser SPA

- [React app and routes](https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/App.jsx): React SPA · Product shell for auth, chat, profiles, and admin. · `src/messenger/frontend_react/src/App.jsx`
- [Chat UI](https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/pages/chat/ChatPage.jsx): React page · `src/messenger/frontend_react/src/pages/chat/ChatPage.jsx`
- [Chat socket hook](https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/hooks/useChatSocket.js): WebSocket client · `src/messenger/frontend_react/src/hooks/useChatSocket.js`
- [Account refresh](https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/src/features/accounts/refreshInterceptor.js): HTTP interceptor · Uses the httpOnly refresh-cookie flow for account switching. · `src/messenger/frontend_react/src/features/accounts/refreshInterceptor.js`
- [PWA push receiver](https://github.com/benzin8/wsnox/blob/main/src/messenger/frontend_react/public/sw.js): Service worker · `src/messenger/frontend_react/public/sw.js`

### FastAPI application

- [FastAPI composition](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/main.py): ASGI application · Serves the SPA, REST API, and WebSocket endpoints. · `src/messenger/backend/app/main.py`
- [Versioned REST routers](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/api_v1/routers/chat_router.py): API boundary · Auth, chat, profile, push, notification, WebAuthn, and admin endpoints. · `src/messenger/backend/app/api_v1/routers/chat_router.py`
- [Identity and RBAC](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/api_v1/auth/dependencies.py): auth dependencies · Validates JWT identity and applies authorization gates. · `src/messenger/backend/app/api_v1/auth/dependencies.py`
- [Security controls](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/core/security.py): security service · Passwords, tokens, rate limits, and permissions. · `src/messenger/backend/core/security.py`
- **Chat and message domain**: CRUD layer · Applies membership, consent, moderation, reactions, and receipts.
- [Message encryption](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/core/crypto.py): AES-GCM service · Encrypts persisted messages and decrypts authorized delivery/search. · `src/messenger/backend/core/crypto.py`
- [Realtime gateway](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/ws/router.py): WebSocket router · Authenticates first JWT-bearing message and handles chat actions. · `src/messenger/backend/app/ws/router.py`
- [Presence and active chat](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/ws/presence.py): realtime state · Tracks transient presence, viewers, and ephemeral events. · `src/messenger/backend/app/ws/presence.py`
- [Media pipeline](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/services/media.py): media service · Sanitizes images/audio/video and issues object access URLs. · `src/messenger/backend/services/media.py`

### Data and realtime state

- [PostgreSQL](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/db/session.py): source-of-truth database · Users, chats, encrypted messages, credentials, subscriptions, and audits. · `src/messenger/backend/db/session.py`
- [Alembic migrations](https://github.com/benzin8/wsnox/blob/main/alembic/env.py): schema evolution · `alembic/env.py`
- [Redis](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/core/redis.py): cache and Pub/Sub · Multi-worker events, cache, rate limits, unread, and TTL state. · `src/messenger/backend/core/redis.py`

### External delivery

- [S3-compatible storage](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/services/storage.py): object storage · Stores uploaded media externally. · `src/messenger/backend/services/storage.py`
- [Web Push delivery](https://github.com/benzin8/wsnox/blob/main/src/messenger/backend/app/ws/push.py): push service · Filters notifications by active chat, mute, and DND. · `src/messenger/backend/app/ws/push.py`

### Deployment

- [Nginx and Compose](https://github.com/benzin8/wsnox/blob/main/nginx/wsnox.conf): production edge · Routes static, API, and WebSocket traffic to containerized services. · `nginx/wsnox.conf`

## Connections

- React app and routes → FastAPI composition: same-origin HTTP
- Chat UI → Chat socket hook: uses
- Chat socket hook → Realtime gateway: WebSocket actions/events
- Account refresh → Versioned REST routers: refreshes session
- FastAPI composition → Versioned REST routers: mounts
- FastAPI composition → Realtime gateway: mounts
- Versioned REST routers → Identity and RBAC: auth dependency
- Identity and RBAC → Security controls: JWT and RBAC
- Versioned REST routers → Chat and message domain: chat commands
- Chat and message domain → Message encryption: encrypt/decrypt
- Chat and message domain → PostgreSQL: persists domain data
- Realtime gateway → Chat and message domain: realtime chat actions
- Realtime gateway → Presence and active chat: updates
- Realtime gateway → Redis: publishes and subscribes
- Presence and active chat → Redis: TTL state
- Versioned REST routers → Media pipeline: uploads
- Media pipeline → S3-compatible storage: stores objects
- Versioned REST routers → Web Push delivery: subscription and notification flow
- Web Push delivery → PWA push receiver: VAPID push
- Alembic migrations → PostgreSQL: evolves schema
- Nginx and Compose → FastAPI composition: proxies API and WebSockets