How eagl3eyes/guptochat works
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: routes REST Routes · index.js Socket Core · docker-compose.yml Compose Stack · lib Core Services
Components 22
Client
React SPA/PWA and local runtime state
- Frontend App · Vite-based client shell with pages, components, stores, and offline behavior
frontend/src/App.jsx - Client State · Auth, chat, contacts, coins, premium, notifications, admin, and random-chat state
frontend/src/store - Chat UI · Conversation, group, and random-chat screens plus message composition and status UI
frontend/src/components - Offline Layer · Service worker, IndexedDB queues, sync consumer, push manager, and network monitoring
frontend/src/sw.js - Commerce UI · Store, currency, coin, and premium purchase flows with related modals and badges
frontend/src/pages/StorePage.jsx - Admin UI · Admin dashboard, moderation tools, analytics, and trust-and-safety controls
frontend/src/components/admin
API
Express REST endpoints and controllers
- REST Routes · Domain route boundaries for auth, messages, groups, matchmaking, commerce, notifications, images, sync, and admin
backend/src/routes - Controllers · Per-domain REST handlers plus the isolated admin control plane
backend/src/controllers - Security Middleware · Auth, admin, CSRF, rate limiting, bot detection, email verification, turnstile, and upload validation
backend/src/middleware - Core 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 · Shared socket server and lifecycle wiring
backend/src/lib/socket/index.js - Messaging Socket · Typing, read receipts, reactions, attachments, and session chat events
backend/src/lib/socket/messaging.js - Matchmaking Socket · Lobby, search, reconnect, priority matching, and session-ended events
backend/src/lib/socket/matchmaking.js - Contacts Socket · Contact sync and live contact-state updates
backend/src/lib/socket/contacts.js - Session 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 · PostgreSQL models, migrations, seed data, and Prisma client boundary
backend/prisma/schema.prisma - Worker Jobs · Cleanup, scheduled tasks, event replay, and operational automation outside HTTP
backend/src/worker.js - Redis · Presence, queues, sessions, and socket fan-out coordination
backend/src/lib/redis.js - PostgreSQL · Primary relational data store behind Prisma
backend/prisma - MinIO · S3-compatible media storage for uploads and attachments
backend/src/lib/storage.js - Compose Stack · Docker Compose runtime for frontend, backend, PostgreSQL, Redis, MinIO, and nginx
docker-compose.yml - Nginx Edge · Landing page and reverse proxy boundary for the deployed surfaces
nginx/nginx.conf
Connections 27
- 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