How raghu128/whatsapp_clone works
1. Overall shape
- This repo is a full-stack WhatsApp-style system built as a Node.js microservices backend plus a React/Vite frontend.
- The backend is split into 7 independently deployable services behind a single API Gateway.
- The main architectural rule is database ownership per service: services do not query each other’s databases directly.
2. Client layer
- The frontend lives in frontend/ and is a React SPA using Zustand stores.
- It talks to the backend through two channels:
- HTTP API calls via the gateway
- Socket.io for real-time chat, typing, receipts, and heartbeat/presence
- Key UI state is separated into auth, chat, notification, and presence stores.
3. API Gateway boundary
- services/api-gateway is the single external entry point on port 3000.
- It handles route-based HTTP proxying and WebSocket proxying to the chat service.
- It also performs stateless JWT validation locally, plus Redis-backed rate limiting and token blacklisting.
- This is the main trust boundary between clients and internal services.
4. Authentication subsystem
- services/auth-service owns registration, login, refresh, logout, and token lifecycle.
- It stores users and refresh tokens in PostgreSQL and uses Redis for revocation/blacklist behavior.
- Auth tokens are JWTs; the gateway can validate them without calling auth-service on every request.
- Auth also exposes gRPC helpers for internal service-to-service use.
5. User and contact subsystem
- services/user-service owns profiles, search, contacts, blocking, and group-related user metadata.
- Its persistence is in PostgreSQL.
- It exposes both REST routes and a gRPC server, which chat-service uses for checks like contact verification and profile lookups.
- This service is the source of truth for user identity, profiles, and contact relationships.
6. Chat and messaging subsystem
- services/chat-service is the core real-time domain service.
- It manages chat room creation, message persistence, message status transitions, and chat history.
- Persistence is in MongoDB, and the README indicates the messages collection is designed for hashed sharding by chatRoomId.
- The service also owns the main Socket.io server used for message delivery and acknowledgements.
7. Real-time routing and presence of connected users
- A major scalability feature is the Redis-backed connection directory used by chat-service.
- Instead of broadcasting across all chat nodes, the system can route a message to the specific node where the recipient is connected.
- Presence signals are separate from chat persistence: presence-service tracks online status/last-seen/typing state in Redis, while chat-service uses that state to enhance UX and delivery behavior.
- Socket.io is also used for message receipts, typing, and heartbeat acknowledgements.
8. Media subsystem
- services/media-service handles file upload and retrieval.
- It uses multipart upload validation and stores media either on local disk or an S3-compatible backend depending on configuration.
- It also contains a BullMQ queue for background media processing, such as thumbnailing.
- This service is intentionally separate from chat so binary handling does not block message delivery.
9. Notification subsystem
- services/notification-service consumes events asynchronously and stores notification records in MongoDB.
- It uses Redis Pub/Sub and BullMQ for event intake and retryable jobs.
- This service is the async delivery path for non-chat notification workflows, with storage that supports TTL/retention behavior.
- The README indicates push channels are planned/prepared, while the current implementation centers on backend notification processing.
10. Shared infrastructure package
- shared/ contains cross-cutting building blocks used by all services.
- Important shared pieces include:
- environment validation
- common middleware such as error handling and request validation
- event names/schemas and event bus helpers
- shared logging and response formatting
- AES-GCM encryption utilities
- gRPC proto definitions for auth and user communication
- This package reduces drift across services and centralizes contract definitions.
11. Inter-service communication patterns
- The repo uses three distinct communication styles:
- REST/HTTP for external API access through the gateway
- gRPC for synchronous internal calls where low latency and typed contracts matter
- Redis Pub/Sub + queues for asynchronous workflows and retries
- The most important synchronous dependency is chat-service → user-service for contact checks and user lookups.
- The most important async dependency is event-driven handoff into notifications and background jobs.
12. Security and data handling
- Message content is encrypted at rest with AES-256-GCM before being stored in MongoDB.
- Authentication uses bcrypt for passwords, JWT access/refresh tokens, and Redis-based revocation.
- The system enforces “contacts can start chats” at multiple layers: REST, Socket.io message send, and frontend UX.
- Rate limiting, CORS, Helmet, and structured logging are part of the service edge hardening.
13. Deployment and runtime
- The repo is set up to run as a Docker Compose stack with separate containers for each service and datastore.
- Infra includes PostgreSQL, MongoDB, and Redis, each serving a distinct slice of the system.
- The backend is built for horizontal scaling, especially chat-service and presence-service, while the gateway remains stateless.
- The frontend is built separately and served through Nginx in production.
14. How requests flow end-to-end
- A typical login or profile request goes: Frontend → API Gateway → target service → its database.
- A chat send path goes: Frontend socket → Gateway → chat-service → encryption/persistence → Redis node lookup → recipient socket.
- A contact-gated chat creation path adds one more hop: chat-service → gRPC → user-service before room creation.
- Async side effects, like notifications or media processing, are pushed into Redis-backed workers instead of blocking the user-facing path.
Main entry points: routes.js Route Proxy · App.jsx Chat UI · src/app.js Chat Service · src/app.js Auth Service
Components 26
Frontend
React/Vite client with local UI state and API/socket integration
- Chat UI · React/Vite single-page app with Zustand stores for auth, chat, notifications, and presence
frontend/src/App.jsx - API Client · Frontend HTTP layer for gateway-backed REST calls
frontend/src/services/api.js - Socket Client · Frontend real-time client for chat delivery, typing, receipts, and heartbeat
frontend/src/services/socket.js - Auth Store · Client auth/session state management
frontend/src/stores/authStore.js - Chat Store · Client chat history, room, and message state
frontend/src/stores/chatStore.js - Presence Store · Client presence and typing indicators
frontend/src/stores/presenceStore.js - Notif Store · Client notification state and badges
frontend/src/stores/notificationStore.js
Edge Layer
External entry point, auth validation, and request routing
- API Gateway · Single external entry point for HTTP routing, WebSocket proxying, JWT validation, and rate limiting
services/api-gateway/src/app.js - JWT Guard · Stateless token validation and request authentication at the gateway
services/api-gateway/src/middleware/auth.js - Route Proxy · Route-based HTTP forwarding to internal services
services/api-gateway/src/proxy/routes.js - Rate Limiter · Redis-backed request throttling and token blacklist support
services/api-gateway/src/middleware/rateLimiter.js
Backend Services
Independently deployable domain services with owned data stores
- Auth Service · Registration, login, refresh, logout, and token lifecycle ownership
services/auth-service/src/app.js - User Service · Profiles, search, contacts, blocking, and group-related user metadata
services/user-service/src/app.js - Chat Service · Core messaging service for rooms, message persistence, status transitions, and Socket.io delivery
services/chat-service/src/app.js - Media Service · File upload, retrieval, storage backend selection, and background media processing
services/media-service/src/app.js - Notification Service · Event-driven notification processing with retries and stored notification records
services/notification-service/src/app.js - Presence Service · Online status, last-seen, and typing state tracking in Redis
services/presence-service/src/app.js - Auth DB · Auth users and refresh tokens
services/auth-service/src/config/database.js - User DB · User profiles, contacts, and group membership
services/user-service/src/config/database.js - Chat DB · Chat rooms and encrypted message persistence with sharding by chatRoomId
services/chat-service/src/config/database.js - Media Store · Binary media persistence on local disk or S3-compatible storage
services/media-service/src/utils/storage.js - Notif DB · Notification records with retention/TTL behavior
services/notification-service/src/config/database.js - Presence Redis · Presence and typing state store
services/presence-service/src/config/redis.js
Shared Core
Common contracts, middleware, and utilities reused across services
- Shared Event Bus · Cross-service event names, schemas, and helpers
shared/events/eventBus.js - gRPC Protos · Typed service contracts for auth and user communication
shared/proto/auth.proto - Shared Utils · Environment validation, logging, response formatting, encryption, and middleware
shared/index.js
Connections 37
- Chat UI → API Client: REST · UI data fetches and mutations through the gateway
- Chat UI → Socket Client: realtime · Live chat and presence connection
- API Client → API Gateway: HTTP · Client API requests enter through the gateway
- Socket Client → API Gateway: Socket.io · WebSocket traffic is proxied via the gateway to chat service
- API Gateway → JWT Guard: auth · Validates JWTs locally without calling auth service on every request
- API Gateway → Rate Limiter: limit · Applies Redis-backed rate limiting and blacklist checks
- API Gateway → Route Proxy: route · Forwards requests to the appropriate internal service
- Route Proxy → Auth Service: auth API · Routes auth-related HTTP traffic
- Route Proxy → User Service: user API · Routes profile/contact HTTP traffic
- Route Proxy → Chat Service: chat API · Routes chat-related HTTP traffic
- Route Proxy → Media Service: media API · Routes upload/retrieval HTTP traffic
- Route Proxy → Notification Service: notif API · Routes notification HTTP traffic
- Route Proxy → Presence Service: presence API · Routes presence HTTP traffic
- Auth Service → Auth DB: owns · Auth data is stored in its own PostgreSQL database
- User Service → User DB: owns · User data is stored in its own PostgreSQL database
- Chat Service → Chat DB: owns · Chat data is stored in MongoDB
- Media Service → Media Store: stores · Media is persisted to disk or S3-compatible storage
- Notification Service → Notif DB: owns · Notifications are stored in MongoDB
- Presence Service → Presence Redis: owns · Presence state is tracked in Redis
- Auth Service → gRPC Protos: grpc · Exports gRPC helpers for internal callers
- User Service → gRPC Protos: grpc · Serves gRPC for internal profile/contact lookups
- Chat Service → gRPC Protos: grpc client · Calls user service synchronously for contact checks and lookups
- Chat Service → Presence Service: presence · Consumes online/typing state to improve delivery behavior
- Chat Service → Shared Event Bus: events · Publishes domain events for async consumers
- Auth Service → Shared Event Bus: events · Publishes auth-related events
- User Service → Shared Event Bus: events · Publishes user/contact events
- Notification Service → Shared Event Bus: subscribes · Consumes events asynchronously for notification workflows
- Media Service → Shared Event Bus: jobs · Uses queue-backed background processing for media tasks
- Notification Service → Shared Utils: shared code · Uses common middleware, logging, and validation helpers
- Auth Service → Shared Utils: shared code · Uses shared middleware, logging, and token helpers
- Chat Service → Shared Utils: shared code · Uses encryption, logging, and validation helpers
- User Service → Shared Utils: shared code · Uses shared middleware and utilities
- Media Service → Shared Utils: shared code · Uses shared validation and response helpers
- Chat UI → Auth Store: state · Auth/session state in the client
- Chat UI → Chat Store: state · Conversation state in the client
- Chat UI → Presence Store: state · Presence state in the client
- Chat UI → Notif Store: state · Notification state in the client