benzin8/wsnox

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.