voidjack233/void-chats

1. The repo is a split chat system, not a single app. The main runtime pieces are:

- VOID0000-www: React + TypeScript + Vite frontend

- VOID0000-api: Node/Express backend split into multiple service entrypoints

- VOID0000-api/void_gateway: Phoenix/Elixir realtime gateway

- VOIDADMIN: a small separate admin panel

Root server.js and root package.json are legacy remnants and not part of the normal path.

2. The frontend is the user-facing shell. It owns routing, UI state, and most client-side orchestration for auth, chat, friends, profile, settings, notifications, and encrypted media flows. The main architectural boundary is that the frontend talks to the API over HTTP and to the gateway for realtime presence/chat fanout.

3. The frontend is also where the crypto-heavy client logic lives. VOID0000-www/src/Services/Crypto and .../Chat handle message encryption/decryption, MLS group state, key management, attachment encryption, queued sends, conversation caches, and sync. A vendored ts-mls copy is included under VOID0000-www/vendor/ts-mls, so MLS behavior is intentionally pinned.

4. The backend is split by responsibility rather than a single monolith. The entrypoints in VOID0000-api/server/entrypoints separate account, conversation, message, social, and worker processes. That means the architecture has distinct process boundaries for HTTP APIs, background work, and any shared infrastructure they all depend on.

5. Authentication and account management are centralized in the Node API. The server/routes/auth and server/routes/user areas cover registration, login, refresh, logout, password changes, email verification, 2FA, session management, profile reads/updates, and account preferences. Supporting middleware handles JWTs, encrypted CSRF, session storage, captcha checks, email delivery, and rate limiting.

6. Chat data is split across storage systems. PostgreSQL migrations define the core application schema: users, conversations, membership, reactions, invites, MLS metadata, push subscriptions, and recovery/backups. ScyllaDB migrations under db/scylla-migrations store message-oriented data and message metadata, which is a clear separation between relational control data and high-volume message storage.

7. Realtime behavior is handled by the Phoenix gateway, not by Express. The gateway’s job is presence, socket auth, connection tracking, session buffering, event dispatch, and fanout. The Node side includes server/gateway and valkey-pubsub integration, which suggests Node publishes events into shared infrastructure and Phoenix distributes them to connected clients.

8. Valkey/Redis is the coordination layer between services. It appears in rate limiting, pub/sub, session-related state, and gateway coordination. This is a key architecture boundary: stateless HTTP services rely on shared in-memory infrastructure for throttling, presence/event propagation, and short-lived coordination.

9. Media and file handling are separated from message transport. MinIO is used for object storage, and the backend includes private attachment routes plus MinIO integration. The frontend also has encrypted attachment flows, while server-side image processing via sharp is used for non-encrypted assets like avatars. The repo notes that profile/group pictures are public-read, while chat attachment blobs are private and fetched through authenticated API paths.

10. Background processing exists for non-interactive work. server/queues/imageQueue.js and the worker-server entrypoint indicate asynchronous jobs, likely for image processing, cleanup, or other deferred tasks. This keeps heavier work off the request path.

11. Notifications are a separate subsystem. The backend has server/notifications/webPush.js and push-subscription migrations, while the frontend includes a service worker (public/push-sw.js) and notification prompting UI. So push notifications are end-to-end: subscription storage in the API, delivery from backend, and browser handling in the client.

12. Messaging features are layered on top of a larger conversation model. The conversation routes cover groups, DMs, member roles, invites, permissions, reactions, read state, typing, attachments, and MLS-specific endpoints like key packages, commits, welcomes, group states, sync, and recovery artifacts. This is the core product domain and is split into normal chat operations plus MLS lifecycle management.

13. Presence and friend discovery are separate from chat rooms. The friends routes and corresponding frontend hooks/components handle requests, lists, pending states, and presence. This is useful for diagramming because “social graph/presence” is not embedded inside conversation handling; it is its own API slice.

14. The deployment model assumes internal services behind a public front door. The README and docs indicate Nginx and Cloudflared are used as the public edge, while backend, gateway, and storage services are meant to stay loopback-only. So the architecture is “edge proxy/tunnel in front, private internal services behind.”

15. The admin app is a standalone internal tool. VOIDADMIN is a separate Express app with its own public assets and server, likely used for user/security oversight rather than normal end-user chat flow. It should be diagrammed as an auxiliary operational surface, not part of the main client path.

16. In diagram terms, the most important flows are:

- Browser UI → Express API for auth, profiles, conversations, media, and history

- Browser UI → Phoenix gateway for realtime presence/chat updates

- Express services ↔ PostgreSQL for control data

- Express services ↔ ScyllaDB for message storage

- Express services ↔ MinIO for attachments/media

- Express services ↔ Valkey for coordination, rate limits, and pub/sub

- Frontend crypto layer handles encryption/decryption before payloads cross those boundaries