# eagl3eyes/guptochat architecture

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

- Interactive diagram: https://gitdiagram.com/eagl3eyes/guptochat
- Repository: https://github.com/eagl3eyes/guptochat

## Overview

1. **Repository shape and deployment boundary**
   - This is a monorepo with three deployable surfaces: `frontend/` (React SPA/PWA), `backend/` (Express + Socket.IO API), and `nginx/` (static landing page / reverse proxy config).
   - The system is designed to run via Docker Compose with PostgreSQL, Redis, and MinIO as the main infrastructure dependencies.

2. **Client application layer**
   - The frontend is a React 19 + Vite app organized around pages, reusable UI components, Zustand stores, and small utility libraries.
   - React Query is used for server-state fetching/caching, while Zustand stores hold app-wide UI/session state for chat, auth, coins, premium, notifications, random chat, and admin.
   - The frontend is not just a view layer: it also owns offline behavior via a service worker, IndexedDB-backed queues, push handling, and connection/latency monitoring.

3. **Primary interaction model: REST + real-time sockets**
   - The app uses REST endpoints for authentication, profile/admin operations, shop/coin/premium flows, uploads, and query-based fetching.
   - Socket.IO is the real-time backbone for messaging, matchmaking, contacts, session state, typing/read receipts, and random anonymous chat.
   - The architecture is split so REST handles durable CRUD and authentication flows, while sockets carry low-latency event streams.

4. **Backend request layer**
   - `backend/src/routes/*` defines route boundaries by domain, and `backend/src/controllers/*` contains the handlers.
   - Domain separation is strong: auth, messages, groups, matchmaking, notifications, shop, premium, coins, rewards, transactions, images, sync, and contact each have their own controller/route pair.
   - Admin functionality is isolated under `controllers/admin` and `routes/admin.route.js`, which is useful for diagramming a separate privileged control plane.

5. **Backend core services**
   - `backend/src/lib/` contains the core business services that sit underneath controllers: moderation, encryption, storage, email, notification delivery, link previews, image processing, geo lookup, cleanup, event replay, and logging.
   - `socket/` submodules split Socket.IO concerns into contacts, matchmaking, messaging, session, state, and validation, showing that realtime handling is treated as a subsystem rather than mixed into controllers.
   - Several helpers enforce cross-cutting behavior such as app config caching, ban checks, coin transactions, and audit logging.

6. **Data persistence and schema management**
   - Prisma is the ORM boundary between application code and PostgreSQL.
   - The schema/migrations indicate the domain is evolving around messaging performance, refresh-token versioning, and removal of older call-log concepts.
   - Prisma seed data is present, suggesting a bootstrap path for initial admin/config/domain records.

7. **Redis, queueing, and ephemeral state**
   - Redis is used for more than cache: the README calls out presence, queue, and sessions, and the backend includes explicit Redis/queue modules and Socket.IO Redis adapter support.
   - This makes Redis the ephemeral coordination layer for realtime fan-out, session state, and background work, while PostgreSQL remains the source of truth.
   - Any architecture diagram should show Redis sitting between socket workers/instances rather than as a simple cache.

8. **File, media, and encrypted content flow**
   - Media handling is first-class: frontend has image compression, optimized image loading, voice note playback, attachment cards, and media lightbox UI.
   - Backend has upload and file-type validation middleware plus storage/image-processing services, and MinIO is the S3-compatible object store.
   - The README also notes message encryption at rest, which implies message content is not stored as plain text in the database path.

9. **Anonymous matching and chat session lifecycle**
   - Matching is a dedicated subsystem with its own controller, route, socket module, and frontend pages/components for lobby/searching/session-ended/history views.
   - The flow is event-driven: users enter a lobby, the backend matches peers using stored state and filters, and the session is maintained over sockets until disconnect/reconnect or end-of-session actions.
   - Premium priority matching and reconnection windows are part of this path, so the matchmaking graph should connect to auth/premium state.

10. **Messages, contacts, and group conversations**
   - Direct messaging is the largest collaborative subsystem: it includes message composition, reactions, reply/pin, disappearing timers, link previews, typing, read receipts, attachments, and voice notes.
   - Contacts and groups are separate concerns with their own routes, controllers, socket handlers, and frontend surfaces.
   - Group settings and permissions are enforced server-side, with UI support for creating/managing groups and admin-only posting constraints.

11. **Commerce, subscriptions, and rewards**
   - The virtual economy is a distinct domain: coins, shop items, currency conversion, coin packs, reward codes, grants, transactions, and premium tiers all have dedicated backend routes/controllers and frontend stores/modals.
   - This suggests a ledger-like flow where user actions trigger backend coin transactions and then update client state through queries and/or socket events.
   - Premium also affects product behavior beyond billing, particularly matchmaking priority and feature gating.

12. **Moderation, admin, and trust/safety**
   - The admin subsystem has its own UI shell plus backend endpoints for users, bans, reports, announcements, roles, messages, coins, premium, analytics, and anonymous-chat moderation.
   - Moderation helpers include profanity filtering, flood/spam detection, audit logs, ban checks, and report handling.
   - Security controls are layered through middleware: auth, admin authorization, CSRF, rate limiting, bot detection, email verification, Turnstile verification, and upload validation.

13. **Offline, sync, and notification delivery**
   - The frontend PWA stores pending activity locally and uses a sync consumer to reconcile with the backend when connectivity returns.
   - Push notifications are supported through web push/FCM, with a dedicated push route/controller pair on the backend and a push manager on the client.
   - `sync` exists as its own route/controller, which is a hint that offline event reconciliation is an explicit backend contract.

14. **Background processing and operational concerns**
   - `backend/worker.js` plus scripts such as backup installation indicate there is non-HTTP background execution for cleanup, scheduled tasks, event replay, and operational automation.
   - Logging is handled with Pino, and the README mentions Sentry for monitoring.
   - For an architecture diagram, this is the place to show asynchronous jobs, cron-like tasks, backups, and event-processing workers connected to Redis/Postgres.

15. **Quality gates and delivery**
   - Both frontend and backend have Vitest test suites, with schema tests and integration-style tests around auth, groups, matchmaking, messages, and state.
   - GitHub Actions, Dependabot, Husky, and lint-staged indicate the repository is wired for CI, dependency upkeep, and pre-commit checks.
   - This matters architecturally because the system has multiple coupled domains and relies on automated verification to keep REST, sockets, and schema changes aligned.

Main entry points: [`backend/src/routes`](https://github.com/eagl3eyes/guptochat/tree/main/backend/src/routes) (REST Routes), [`backend/src/lib/socket/index.js`](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/index.js) (Socket Core), [`docker-compose.yml`](https://github.com/eagl3eyes/guptochat/blob/main/docker-compose.yml) (Compose Stack), [`backend/src/lib`](https://github.com/eagl3eyes/guptochat/tree/main/backend/src/lib) (Core Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_client["Client"]
  node_frontend_app["Frontend App<br/>React SPA/PWA<br/>[App.jsx]"]
  node_frontend_stores[("Client State<br/>Zustand stores")]
  node_frontend_realtime_ui["Chat UI<br/>messaging views"]
  node_frontend_offline["Offline Layer<br/>PWA runtime<br/>[sw.js]"]
  node_frontend_storefront["Commerce UI<br/>shop and premium<br/>[StorePage.jsx]"]
  node_frontend_admin["Admin UI<br/>privileged panel"]
end

subgraph group_group_api["API"]
  node_api_routes["REST Routes<br/>Express routes"]
  node_api_controllers["Controllers<br/>request handlers"]
  node_api_security{{"Security Middleware<br/>guards"}}
  node_api_shared_lib["Core Services<br/>business services"]
end

subgraph group_group_realtime["Realtime"]
  node_realtime_socket(("Socket Core<br/>Socket.IO hub<br/>[index.js]"))
  node_realtime_messaging["Messaging Socket<br/>realtime messaging<br/>[messaging.js]"]
  node_realtime_matchmaking["Matchmaking Socket<br/>anonymous chat<br/>[matchmaking.js]"]
  node_realtime_contacts["Contacts Socket<br/>presence/contacts<br/>[contacts.js]"]
  node_realtime_session[("Session State<br/>ephemeral state<br/>[session.js]")]
end

subgraph group_group_data["Data & Infra"]
  node_api_schema[("Prisma Layer<br/>ORM schema<br/>[schema.prisma]")]
  node_api_worker["Worker Jobs<br/>background jobs<br/>[worker.js]"]
  node_redis[("Redis<br/>ephemeral store<br/>[redis.js]")]
  node_postgres[("PostgreSQL<br/>system of record")]
  node_minio[("MinIO<br/>object storage<br/>[storage.js]")]
  node_docker["Compose Stack<br/>deployment<br/>[docker-compose.yml]"]
  node_nginx_edge["Nginx Edge<br/>reverse proxy<br/>[nginx.conf]"]
end

node_frontend_app -->|"REST"| node_api_routes
node_frontend_app -->|"sockets"| node_realtime_socket
node_frontend_stores -->|"state"| node_frontend_app
node_frontend_realtime_ui -->|"binds"| node_frontend_stores
node_frontend_offline -.->|"reconnect"| node_realtime_socket
node_frontend_offline -->|"sync"| node_api_routes
node_frontend_storefront -->|"commerce"| node_api_routes
node_frontend_admin -->|"admin REST"| node_api_routes
node_api_routes -->|"dispatch"| node_api_controllers
node_api_controllers -->|"guarded by"| node_api_security
node_api_controllers -->|"uses"| node_api_shared_lib
node_api_shared_lib -->|"persists"| node_api_schema
node_api_shared_lib -->|"ephemeral"| node_redis
node_api_shared_lib -->|"media"| node_minio
node_realtime_socket -->|"routes"| node_realtime_messaging
node_realtime_socket -->|"routes"| node_realtime_matchmaking
node_realtime_socket -->|"routes"| node_realtime_contacts
node_realtime_socket -->|"shares"| node_realtime_session
node_realtime_session -->|"backed by"| node_redis
node_realtime_matchmaking -.->|"session data"| node_api_routes
node_api_worker -->|"jobs"| node_api_schema
node_api_worker -->|"queue"| node_redis
node_api_routes -->|"data"| node_postgres
node_docker -->|"exposes"| node_nginx_edge
node_docker -->|"runs"| node_postgres
node_docker -->|"runs"| node_redis
node_docker -->|"runs"| node_minio

click node_frontend_app "https://github.com/eagl3eyes/guptochat/blob/main/frontend/src/App.jsx"
click node_frontend_stores "https://github.com/eagl3eyes/guptochat/tree/main/frontend/src/store"
click node_frontend_realtime_ui "https://github.com/eagl3eyes/guptochat/tree/main/frontend/src/components"
click node_frontend_offline "https://github.com/eagl3eyes/guptochat/blob/main/frontend/src/sw.js"
click node_frontend_storefront "https://github.com/eagl3eyes/guptochat/blob/main/frontend/src/pages/StorePage.jsx"
click node_frontend_admin "https://github.com/eagl3eyes/guptochat/tree/main/frontend/src/components/admin"
click node_api_routes "https://github.com/eagl3eyes/guptochat/tree/main/backend/src/routes"
click node_api_controllers "https://github.com/eagl3eyes/guptochat/tree/main/backend/src/controllers"
click node_api_security "https://github.com/eagl3eyes/guptochat/tree/main/backend/src/middleware"
click node_api_shared_lib "https://github.com/eagl3eyes/guptochat/tree/main/backend/src/lib"
click node_api_schema "https://github.com/eagl3eyes/guptochat/blob/main/backend/prisma/schema.prisma"
click node_api_worker "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/worker.js"
click node_realtime_socket "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/index.js"
click node_realtime_messaging "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/messaging.js"
click node_realtime_matchmaking "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/matchmaking.js"
click node_realtime_contacts "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/contacts.js"
click node_realtime_session "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/session.js"
click node_redis "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/redis.js"
click node_postgres "https://github.com/eagl3eyes/guptochat/tree/main/backend/prisma"
click node_minio "https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/storage.js"
click node_docker "https://github.com/eagl3eyes/guptochat/blob/main/docker-compose.yml"
click node_nginx_edge "https://github.com/eagl3eyes/guptochat/blob/main/nginx/nginx.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_frontend_app,node_frontend_stores,node_frontend_realtime_ui,node_frontend_offline,node_frontend_storefront,node_frontend_admin toneBlue
class node_api_routes,node_api_controllers,node_api_security,node_api_shared_lib toneAmber
class node_realtime_socket,node_realtime_messaging,node_realtime_matchmaking,node_realtime_contacts,node_realtime_session toneMint
class node_api_schema,node_api_worker,node_redis,node_postgres,node_minio,node_docker,node_nginx_edge toneRose
```

## Components

### Client

React SPA/PWA and local runtime state

- [Frontend App](https://github.com/eagl3eyes/guptochat/blob/main/frontend/src/App.jsx): React SPA/PWA · Vite-based client shell with pages, components, stores, and offline behavior · `frontend/src/App.jsx`
- [Client State](https://github.com/eagl3eyes/guptochat/tree/main/frontend/src/store): Zustand stores · Auth, chat, contacts, coins, premium, notifications, admin, and random-chat state · `frontend/src/store`
- [Chat UI](https://github.com/eagl3eyes/guptochat/tree/main/frontend/src/components): messaging views · Conversation, group, and random-chat screens plus message composition and status UI · `frontend/src/components`
- [Offline Layer](https://github.com/eagl3eyes/guptochat/blob/main/frontend/src/sw.js): PWA runtime · Service worker, IndexedDB queues, sync consumer, push manager, and network monitoring · `frontend/src/sw.js`
- [Commerce UI](https://github.com/eagl3eyes/guptochat/blob/main/frontend/src/pages/StorePage.jsx): shop and premium · Store, currency, coin, and premium purchase flows with related modals and badges · `frontend/src/pages/StorePage.jsx`
- [Admin UI](https://github.com/eagl3eyes/guptochat/tree/main/frontend/src/components/admin): privileged panel · Admin dashboard, moderation tools, analytics, and trust-and-safety controls · `frontend/src/components/admin`

### API

Express REST endpoints and controllers

- [REST Routes](https://github.com/eagl3eyes/guptochat/tree/main/backend/src/routes): Express routes · Domain route boundaries for auth, messages, groups, matchmaking, commerce, notifications, images, sync, and admin · `backend/src/routes`
- [Controllers](https://github.com/eagl3eyes/guptochat/tree/main/backend/src/controllers): request handlers · Per-domain REST handlers plus the isolated admin control plane · `backend/src/controllers`
- [Security Middleware](https://github.com/eagl3eyes/guptochat/tree/main/backend/src/middleware): guards · Auth, admin, CSRF, rate limiting, bot detection, email verification, turnstile, and upload validation · `backend/src/middleware`
- [Core Services](https://github.com/eagl3eyes/guptochat/tree/main/backend/src/lib): business services · Encryption, moderation, storage, notifications, image processing, link previews, geo lookup, logging, cleanup, and audit helpers · `backend/src/lib`

### Realtime

Socket.IO event handling and ephemeral coordination

- [Socket Core](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/index.js): Socket.IO hub · Shared socket server and lifecycle wiring · `backend/src/lib/socket/index.js`
- [Messaging Socket](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/messaging.js): realtime messaging · Typing, read receipts, reactions, attachments, and session chat events · `backend/src/lib/socket/messaging.js`
- [Matchmaking Socket](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/matchmaking.js): anonymous chat · Lobby, search, reconnect, priority matching, and session-ended events · `backend/src/lib/socket/matchmaking.js`
- [Contacts Socket](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/contacts.js): presence/contacts · Contact sync and live contact-state updates · `backend/src/lib/socket/contacts.js`
- [Session State](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/socket/session.js): ephemeral state · Session lifecycle, presence, Redis-backed coordination, and validation · `backend/src/lib/socket/session.js`

### Data & Infra

Persistence, object storage, queues, and deployment dependencies

- [Prisma Layer](https://github.com/eagl3eyes/guptochat/blob/main/backend/prisma/schema.prisma): ORM schema · PostgreSQL models, migrations, seed data, and Prisma client boundary · `backend/prisma/schema.prisma`
- [Worker Jobs](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/worker.js): background jobs · Cleanup, scheduled tasks, event replay, and operational automation outside HTTP · `backend/src/worker.js`
- [Redis](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/redis.js): ephemeral store · Presence, queues, sessions, and socket fan-out coordination · `backend/src/lib/redis.js`
- [PostgreSQL](https://github.com/eagl3eyes/guptochat/tree/main/backend/prisma): system of record · Primary relational data store behind Prisma · `backend/prisma`
- [MinIO](https://github.com/eagl3eyes/guptochat/blob/main/backend/src/lib/storage.js): object storage · S3-compatible media storage for uploads and attachments · `backend/src/lib/storage.js`
- [Compose Stack](https://github.com/eagl3eyes/guptochat/blob/main/docker-compose.yml): deployment · Docker Compose runtime for frontend, backend, PostgreSQL, Redis, MinIO, and nginx · `docker-compose.yml`
- [Nginx Edge](https://github.com/eagl3eyes/guptochat/blob/main/nginx/nginx.conf): reverse proxy · Landing page and reverse proxy boundary for the deployed surfaces · `nginx/nginx.conf`

## Connections

- Frontend App → REST Routes: REST · Client calls authenticated and domain REST endpoints
- Frontend App → Socket Core: sockets · Client maintains low-latency realtime connection
- Client State → Frontend App: state · App shell reads and writes global UI/session state
- Chat UI → Client State: binds · Chat surfaces drive store updates and consume cached state
- Offline Layer → Socket Core: reconnect · Offline queue and sync logic recover into realtime state
- Offline Layer → REST Routes: sync · Pending client actions reconcile through REST sync and push endpoints
- Commerce UI → REST Routes: commerce · Store and premium flows fetch and mutate server state
- Admin UI → REST Routes: admin REST · Privileged operations use admin endpoints
- REST Routes → Controllers: dispatch · Routes hand off to domain controllers
- Controllers → Security Middleware: guarded by · Requests pass through auth and validation middleware
- Controllers → Core Services: uses · Controllers rely on shared business services
- Core Services → Prisma Layer: persists · Services read and write through Prisma
- Core Services → Redis: ephemeral · Shared services use Redis for coordination and queues
- Core Services → MinIO: media · Uploads and image services store objects in MinIO
- Socket Core → Messaging Socket: routes · Socket hub delegates message events to messaging subsystem
- Socket Core → Matchmaking Socket: routes · Socket hub delegates anonymous-chat events
- Socket Core → Contacts Socket: routes · Socket hub delegates contact/presence events
- Socket Core → Session State: shares · Socket handlers coordinate session and presence state
- Session State → Redis: backed by · Ephemeral session state is coordinated in Redis
- Matchmaking Socket → REST Routes: session data · Matchmaking depends on durable auth, premium, and sync state
- Worker Jobs → Prisma Layer: jobs · Background tasks operate on persistent records
- Worker Jobs → Redis: queue · Workers consume queued and replayed work from Redis
- REST Routes → PostgreSQL: data · REST operations ultimately persist to PostgreSQL
- Compose Stack → Nginx Edge: exposes · Compose deployment includes the edge proxy and landing surface
- Compose Stack → PostgreSQL: runs · Compose stack provisions the database
- Compose Stack → Redis: runs · Compose stack provisions ephemeral coordination services
- Compose Stack → MinIO: runs · Compose stack provisions object storage