# raghu128/whatsapp_clone architecture

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

- Interactive diagram: https://gitdiagram.com/raghu128/whatsapp_clone
- Repository: https://github.com/raghu128/whatsapp_clone

## Overview

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: [`services/api-gateway/src/proxy/routes.js`](https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/proxy/routes.js) (Route Proxy), [`frontend/src/App.jsx`](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/App.jsx) (Chat UI), [`services/chat-service/src/app.js`](https://github.com/raghu128/whatsapp_clone/blob/main/services/chat-service/src/app.js) (Chat Service), [`services/auth-service/src/app.js`](https://github.com/raghu128/whatsapp_clone/blob/main/services/auth-service/src/app.js) (Auth Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_spa["Chat UI<br/>react spa<br/>[App.jsx]"]
  node_api_client["API Client<br/>http client<br/>[api.js]"]
  node_socket_client["Socket Client<br/>socket.io client<br/>[socket.js]"]
  node_auth_store["Auth Store<br/>ui state<br/>[authStore.js]"]
  node_chat_store["Chat Store<br/>ui state<br/>[chatStore.js]"]
  node_presence_store["Presence Store<br/>ui state<br/>[presenceStore.js]"]
  node_notification_store["Notif Store<br/>ui state"]
end

subgraph group_edge["Edge Layer"]
  node_gateway["API Gateway<br/>edge proxy<br/>[app.js]"]
  node_gateway_auth["JWT Guard<br/>middleware<br/>[auth.js]"]
  node_gateway_proxy["Route Proxy<br/>proxy router<br/>[routes.js]"]
  node_gateway_rl["Rate Limiter<br/>redis middleware<br/>[rateLimiter.js]"]
end

subgraph group_services["Backend Services"]
  node_auth_svc["Auth Service<br/>[app.js]"]
  node_user_svc["User Service<br/>profile service<br/>[app.js]"]
  node_chat_svc["Chat Service<br/>realtime service<br/>[app.js]"]
  node_media_svc["Media Service<br/>upload service<br/>[app.js]"]
  node_notif_svc["Notification Service<br/>async worker<br/>[app.js]"]
  node_presence_svc["Presence Service<br/>presence cache<br/>[app.js]"]
  node_auth_db[("Auth DB<br/>postgresql<br/>[database.js]")]
  node_user_db[("User DB<br/>postgresql<br/>[database.js]")]
  node_chat_db[("Chat DB<br/>mongodb<br/>[database.js]")]
  node_media_store[("Media Store<br/>filesystem/s3<br/>[storage.js]")]
  node_notif_db[("Notif DB<br/>mongodb<br/>[database.js]")]
  node_presence_store_backend[("Presence Redis<br/>[redis.js]")]
end

subgraph group_shared["Shared Core"]
  node_event_bus["Shared Event Bus<br/>contracts<br/>[eventBus.js]"]
  node_grpc_protos["gRPC Protos<br/>contracts<br/>[auth.proto]"]
  node_shared_utils["Shared Utils<br/>common library<br/>[index.js]"]
end

node_spa -->|"REST"| node_api_client
node_spa -->|"realtime"| node_socket_client
node_api_client -->|"HTTP"| node_gateway
node_socket_client -->|"Socket.io"| node_gateway
node_gateway -->|"auth"| node_gateway_auth
node_gateway -->|"limit"| node_gateway_rl
node_gateway -->|"route"| node_gateway_proxy
node_gateway_proxy -->|"auth API"| node_auth_svc
node_gateway_proxy -->|"user API"| node_user_svc
node_gateway_proxy -->|"chat API"| node_chat_svc
node_gateway_proxy -->|"media API"| node_media_svc
node_gateway_proxy -->|"notif API"| node_notif_svc
node_gateway_proxy -->|"presence API"| node_presence_svc
node_auth_svc -->|"owns"| node_auth_db
node_user_svc -->|"owns"| node_user_db
node_chat_svc -->|"owns"| node_chat_db
node_media_svc -->|"stores"| node_media_store
node_notif_svc -->|"owns"| node_notif_db
node_presence_svc -->|"owns"| node_presence_store_backend
node_auth_svc -->|"grpc"| node_grpc_protos
node_user_svc -->|"grpc"| node_grpc_protos
node_chat_svc -->|"grpc client"| node_grpc_protos
node_chat_svc -->|"presence"| node_presence_svc
node_chat_svc -->|"events"| node_event_bus
node_auth_svc -->|"events"| node_event_bus
node_user_svc -->|"events"| node_event_bus
node_notif_svc -->|"subscribes"| node_event_bus
node_media_svc -->|"jobs"| node_event_bus
node_notif_svc -->|"shared code"| node_shared_utils
node_auth_svc -->|"shared code"| node_shared_utils
node_chat_svc -->|"shared code"| node_shared_utils
node_user_svc -->|"shared code"| node_shared_utils
node_media_svc -->|"shared code"| node_shared_utils
node_spa -->|"state"| node_auth_store
node_spa -->|"state"| node_chat_store
node_spa -->|"state"| node_presence_store
node_spa -->|"state"| node_notification_store

click node_spa "https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/services/api.js"
click node_socket_client "https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/services/socket.js"
click node_auth_store "https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/authStore.js"
click node_chat_store "https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/chatStore.js"
click node_presence_store "https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/presenceStore.js"
click node_notification_store "https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/notificationStore.js"
click node_gateway "https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/app.js"
click node_gateway_auth "https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/middleware/auth.js"
click node_gateway_proxy "https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/proxy/routes.js"
click node_gateway_rl "https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/middleware/rateLimiter.js"
click node_auth_svc "https://github.com/raghu128/whatsapp_clone/blob/main/services/auth-service/src/app.js"
click node_user_svc "https://github.com/raghu128/whatsapp_clone/blob/main/services/user-service/src/app.js"
click node_chat_svc "https://github.com/raghu128/whatsapp_clone/blob/main/services/chat-service/src/app.js"
click node_media_svc "https://github.com/raghu128/whatsapp_clone/blob/main/services/media-service/src/app.js"
click node_notif_svc "https://github.com/raghu128/whatsapp_clone/blob/main/services/notification-service/src/app.js"
click node_presence_svc "https://github.com/raghu128/whatsapp_clone/blob/main/services/presence-service/src/app.js"
click node_auth_db "https://github.com/raghu128/whatsapp_clone/blob/main/services/auth-service/src/config/database.js"
click node_user_db "https://github.com/raghu128/whatsapp_clone/blob/main/services/user-service/src/config/database.js"
click node_chat_db "https://github.com/raghu128/whatsapp_clone/blob/main/services/chat-service/src/config/database.js"
click node_media_store "https://github.com/raghu128/whatsapp_clone/blob/main/services/media-service/src/utils/storage.js"
click node_notif_db "https://github.com/raghu128/whatsapp_clone/blob/main/services/notification-service/src/config/database.js"
click node_presence_store_backend "https://github.com/raghu128/whatsapp_clone/blob/main/services/presence-service/src/config/redis.js"
click node_event_bus "https://github.com/raghu128/whatsapp_clone/blob/main/shared/events/eventBus.js"
click node_grpc_protos "https://github.com/raghu128/whatsapp_clone/blob/main/shared/proto/auth.proto"
click node_shared_utils "https://github.com/raghu128/whatsapp_clone/blob/main/shared/index.js"

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_spa,node_api_client,node_socket_client,node_auth_store,node_chat_store,node_presence_store,node_notification_store toneBlue
class node_gateway,node_gateway_auth,node_gateway_proxy,node_gateway_rl toneAmber
class node_auth_svc,node_user_svc,node_chat_svc,node_media_svc,node_notif_svc,node_presence_svc,node_auth_db,node_user_db,node_chat_db,node_media_store,node_notif_db,node_presence_store_backend toneMint
class node_event_bus,node_grpc_protos,node_shared_utils toneRose
```

## Components

### Frontend

React/Vite client with local UI state and API/socket integration

- [Chat UI](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/App.jsx): react spa · React/Vite single-page app with Zustand stores for auth, chat, notifications, and presence · `frontend/src/App.jsx`
- [API Client](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/services/api.js): http client · Frontend HTTP layer for gateway-backed REST calls · `frontend/src/services/api.js`
- [Socket Client](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/services/socket.js): socket.io client · Frontend real-time client for chat delivery, typing, receipts, and heartbeat · `frontend/src/services/socket.js`
- [Auth Store](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/authStore.js): ui state · Client auth/session state management · `frontend/src/stores/authStore.js`
- [Chat Store](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/chatStore.js): ui state · Client chat history, room, and message state · `frontend/src/stores/chatStore.js`
- [Presence Store](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/presenceStore.js): ui state · Client presence and typing indicators · `frontend/src/stores/presenceStore.js`
- [Notif Store](https://github.com/raghu128/whatsapp_clone/blob/main/frontend/src/stores/notificationStore.js): ui state · Client notification state and badges · `frontend/src/stores/notificationStore.js`

### Edge Layer

External entry point, auth validation, and request routing

- [API Gateway](https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/app.js): edge proxy · Single external entry point for HTTP routing, WebSocket proxying, JWT validation, and rate limiting · `services/api-gateway/src/app.js`
- [JWT Guard](https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/middleware/auth.js): middleware · Stateless token validation and request authentication at the gateway · `services/api-gateway/src/middleware/auth.js`
- [Route Proxy](https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/proxy/routes.js): proxy router · Route-based HTTP forwarding to internal services · `services/api-gateway/src/proxy/routes.js`
- [Rate Limiter](https://github.com/raghu128/whatsapp_clone/blob/main/services/api-gateway/src/middleware/rateLimiter.js): redis middleware · 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](https://github.com/raghu128/whatsapp_clone/blob/main/services/auth-service/src/app.js): auth service · Registration, login, refresh, logout, and token lifecycle ownership · `services/auth-service/src/app.js`
- [User Service](https://github.com/raghu128/whatsapp_clone/blob/main/services/user-service/src/app.js): profile service · Profiles, search, contacts, blocking, and group-related user metadata · `services/user-service/src/app.js`
- [Chat Service](https://github.com/raghu128/whatsapp_clone/blob/main/services/chat-service/src/app.js): realtime service · Core messaging service for rooms, message persistence, status transitions, and Socket.io delivery · `services/chat-service/src/app.js`
- [Media Service](https://github.com/raghu128/whatsapp_clone/blob/main/services/media-service/src/app.js): upload service · File upload, retrieval, storage backend selection, and background media processing · `services/media-service/src/app.js`
- [Notification Service](https://github.com/raghu128/whatsapp_clone/blob/main/services/notification-service/src/app.js): async worker · Event-driven notification processing with retries and stored notification records · `services/notification-service/src/app.js`
- [Presence Service](https://github.com/raghu128/whatsapp_clone/blob/main/services/presence-service/src/app.js): presence cache · Online status, last-seen, and typing state tracking in Redis · `services/presence-service/src/app.js`
- [Auth DB](https://github.com/raghu128/whatsapp_clone/blob/main/services/auth-service/src/config/database.js): postgresql · Auth users and refresh tokens · `services/auth-service/src/config/database.js`
- [User DB](https://github.com/raghu128/whatsapp_clone/blob/main/services/user-service/src/config/database.js): postgresql · User profiles, contacts, and group membership · `services/user-service/src/config/database.js`
- [Chat DB](https://github.com/raghu128/whatsapp_clone/blob/main/services/chat-service/src/config/database.js): mongodb · Chat rooms and encrypted message persistence with sharding by chatRoomId · `services/chat-service/src/config/database.js`
- [Media Store](https://github.com/raghu128/whatsapp_clone/blob/main/services/media-service/src/utils/storage.js): filesystem/s3 · Binary media persistence on local disk or S3-compatible storage · `services/media-service/src/utils/storage.js`
- [Notif DB](https://github.com/raghu128/whatsapp_clone/blob/main/services/notification-service/src/config/database.js): mongodb · Notification records with retention/TTL behavior · `services/notification-service/src/config/database.js`
- [Presence Redis](https://github.com/raghu128/whatsapp_clone/blob/main/services/presence-service/src/config/redis.js): 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](https://github.com/raghu128/whatsapp_clone/blob/main/shared/events/eventBus.js): contracts · Cross-service event names, schemas, and helpers · `shared/events/eventBus.js`
- [gRPC Protos](https://github.com/raghu128/whatsapp_clone/blob/main/shared/proto/auth.proto): contracts · Typed service contracts for auth and user communication · `shared/proto/auth.proto`
- [Shared Utils](https://github.com/raghu128/whatsapp_clone/blob/main/shared/index.js): common library · Environment validation, logging, response formatting, encryption, and middleware · `shared/index.js`

## Connections

- 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
