# tanvir-art/kafka_whatsapp_clone architecture

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

- Interactive diagram: https://gitdiagram.com/tanvir-art/kafka_whatsapp_clone
- Repository: https://github.com/tanvir-art/kafka_whatsapp_clone

## Overview

1. **Repository shape**
   - This is a microservices-based WhatsApp clone split into four runnable Node.js services plus local infrastructure.
   - The services are: **API Gateway**, **Auth Service**, **Chat Service**, and **Socket Gateway**.
   - Supporting infrastructure is **MongoDB** for persistence, **Kafka** for async events, and **Redis** for presence/state.

2. **System boundary and entry points**
   - The **API Gateway** is the main HTTP entry point for the frontend/client.
   - It exposes the public `/api/auth` and `/api/chat` routes, then proxies requests to the internal auth and chat services.
   - The **Socket Gateway** is a separate real-time entry point for Socket.IO clients.

3. **API Gateway responsibilities**
   - The gateway owns cross-cutting concerns: **authentication middleware**, **rate limiting**, request forwarding, and centralized logging.
   - It does not implement business logic itself; instead it delegates to `authProxy` and `chatProxy`.
   - Architecturally, it is the trust boundary between external clients and internal services.

4. **Auth Service subsystem**
   - The auth service is organized in a classic layered shape: **route → controller → service → model → DB/config**.
   - It handles **registration, login, and refresh-token flow**.
   - JWT logic and password hashing live in service-local utilities, which indicates auth is self-contained and not dependent on the gateway for token creation/verification.

5. **Chat Service subsystem**
   - The chat service owns the core chat domain: **messages** and **groups**.
   - It also follows a route/controller/service/model split, with separate controllers for groups and messages.
   - This service is responsible for persisting chat data in MongoDB and emitting message-related events to Kafka.

6. **Async event flow via Kafka**
   - The key asynchronous path is: **chat service writes message data → publishes Kafka event → socket gateway consumes event**.
   - The Kafka producer lives in the chat service under the message event module.
   - The Kafka consumer lives in the socket gateway, which turns backend events into client-facing Socket.IO updates.

7. **Socket Gateway responsibilities**
   - The socket gateway is the real-time delivery layer, separate from REST APIs.
   - It hosts the Socket.IO server, listens to Kafka message events, and emits socket events to connected clients.
   - It also has a presence service backed by Redis, so online/offline state is not tied to a single process instance.

8. **Redis usage**
   - Redis is used by the socket gateway for **presence tracking**.
   - This keeps ephemeral connection state out of MongoDB and supports fast reads/writes for online user status.
   - Redis is part of the real-time subsystem, not the durable data layer.

9. **Data persistence model**
   - MongoDB is the durable store for both auth and chat domains.
   - Auth service stores user/auth records.
   - Chat service stores chat-specific domain entities such as messages, conversations, and groups.

10. **Runtime and deployment boundaries**
   - Each service has its own `package.json`, `src`, and `server.js`, so they are independently deployable processes.
   - `docker-compose.yml` provides the local infrastructure layer for MongoDB, Redis, and Kafka.
   - The repo is designed for local multi-process development rather than a monolith.

11. **External client flow**
   - A browser/client first authenticates through the API Gateway.
   - Protected chat requests go through the gateway with a JWT bearer token.
   - Real-time UI features connect directly to the Socket Gateway with an access token for Socket.IO auth.

12. **How to draw the architecture**
   - Draw the **frontend/client** at the edge, then the **API Gateway** as the HTTP ingress.
   - Place **Auth Service** and **Chat Service** behind the gateway as separate HTTP microservices.
   - Place **MongoDB** under auth/chat, **Kafka** between chat and socket, and **Redis** under socket.
   - Show the **Socket Gateway** as a parallel ingress for real-time connections, consuming Kafka and emitting Socket.IO events outward.

Main entry points: [`api-gateway/src/app.js`](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/app.js) (API App), [`auth-service/src/app/module/auth.service.js`](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.service.js) (Auth Service), [`chat-service/src/module/services/message.service.js`](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/module/services/message.service.js) (Chat Service), [`socket-gateway/src/socket/socket.server.js`](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/socket/socket.server.js) (Socket Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge"]
  node_client(("Client<br/>browser/app"))
  node_api_app["API App<br/>http gateway<br/>[app.js]"]
  node_api_auth_mw["Auth MW<br/>middleware<br/>[authMiddleware.js]"]
  node_api_rate["Rate Limit<br/>middleware<br/>[rateLimit.js]"]
  node_api_auth_proxy["Auth Proxy<br/>[authProxy.js]"]
  node_api_chat_proxy["Chat Proxy<br/>[chatProxy.js]"]
end

subgraph group_auth["Auth Service"]
  node_auth_route["Auth Route<br/>route layer<br/>[auth.route.js]"]
  node_auth_ctrl["Auth Controller<br/>[auth.controller.js]"]
  node_auth_svc["Auth Service<br/>domain service<br/>[auth.service.js]"]
  node_auth_model[("Auth Model<br/>mongo model<br/>[auth.model.js]")]
  node_auth_db["Auth DB<br/>mongo config<br/>[db.js]"]
end

subgraph group_chat["Chat Service"]
  node_chat_route["Chat Routes<br/>route layer<br/>[message.routes.js]"]
  node_chat_ctrl["Chat Controllers<br/>controller layer"]
  node_chat_svc["Chat Service<br/>domain service<br/>[message.service.js]"]
  node_chat_event["Message Event<br/>kafka producer"]
  node_chat_db["Chat DB<br/>mongo config<br/>[db.js]"]
end

subgraph group_realtime["Realtime"]
  node_socket_server["Socket Server<br/>socket.io ingress<br/>[socket.server.js]"]
  node_socket_consumer["Event Consumer<br/>kafka consumer"]
  node_presence_svc["Presence Service<br/>state service"]
  node_socket_events["Socket Events<br/>event mapping<br/>[socket.events.js]"]
end

subgraph group_infra["Infrastructure"]
  node_socket_redis[("Redis<br/>state store<br/>[redis.js]")]
  node_mongo[("MongoDB<br/>durable store<br/>[db.js]")]
  node_kafka["Kafka<br/>event bus<br/>[kafka.js]"]
end

node_client -->|"HTTP API"| node_api_app
node_client -->|"Socket.IO"| node_socket_server
node_api_app -->|"guard"| node_api_auth_mw
node_api_app -->|"throttle"| node_api_rate
node_api_app -->|"/api/auth"| node_api_auth_proxy
node_api_app -->|"/api/chat"| node_api_chat_proxy
node_api_auth_proxy -->|"forward"| node_auth_route
node_api_chat_proxy -->|"forward"| node_chat_route
node_auth_route -->|"handle"| node_auth_ctrl
node_auth_ctrl -->|"delegate"| node_auth_svc
node_auth_svc -->|"read/write"| node_auth_model
node_auth_svc -->|"connect"| node_auth_db
node_auth_svc -->|"persist"| node_mongo
node_chat_route -->|"handle"| node_chat_ctrl
node_chat_ctrl -->|"delegate"| node_chat_svc
node_chat_svc -->|"connect"| node_chat_db
node_chat_svc -->|"persist"| node_mongo
node_chat_svc -->|"publish"| node_chat_event
node_chat_event -->|"produce"| node_kafka
node_kafka -->|"consume"| node_socket_consumer
node_socket_consumer -->|"emit"| node_socket_events
node_socket_events -->|"deliver"| node_socket_server
node_socket_server -->|"track"| node_presence_svc
node_presence_svc -->|"store"| node_socket_redis
node_socket_redis -.-> node_kafka

click node_api_app "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/app.js"
click node_api_auth_mw "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/middleware/authMiddleware.js"
click node_api_rate "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/middleware/rateLimit.js"
click node_api_auth_proxy "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/services/authProxy.js"
click node_api_chat_proxy "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/services/chatProxy.js"
click node_auth_route "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.route.js"
click node_auth_ctrl "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.controller.js"
click node_auth_svc "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.service.js"
click node_auth_model "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.model.js"
click node_auth_db "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/config/db.js"
click node_chat_route "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/routes/message.routes.js"
click node_chat_ctrl "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/module/controllers/message.controller.js"
click node_chat_svc "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/module/services/message.service.js"
click node_chat_event "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/module/events/message.producer.js"
click node_chat_db "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/config/db.js"
click node_socket_server "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/socket/socket.server.js"
click node_socket_consumer "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/consumers/message.consumer.js"
click node_presence_svc "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/services/presence.service.js"
click node_socket_events "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/socket/socket.events.js"
click node_socket_redis "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/config/redis.js"
click node_mongo "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/config/db.js"
click node_kafka "https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/config/kafka.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_client,node_api_app,node_api_auth_mw,node_api_rate,node_api_auth_proxy,node_api_chat_proxy toneBlue
class node_auth_route,node_auth_ctrl,node_auth_svc,node_auth_model,node_auth_db toneAmber
class node_chat_route,node_chat_ctrl,node_chat_svc,node_chat_event,node_chat_db toneMint
class node_socket_server,node_socket_consumer,node_presence_svc,node_socket_events toneRose
class node_socket_redis,node_mongo,node_kafka toneIndigo
```

## Components

### Edge

External clients and ingress layers

- **Client**: browser/app · Frontend or mobile client
- [API App](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/app.js): http gateway · Main HTTP ingress and trust boundary · `api-gateway/src/app.js`
- [Auth MW](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/middleware/authMiddleware.js): middleware · JWT-bearing request authentication · `api-gateway/src/middleware/authMiddleware.js`
- [Rate Limit](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/middleware/rateLimit.js): middleware · Per-request throttling · `api-gateway/src/middleware/rateLimit.js`
- [Auth Proxy](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/services/authProxy.js): proxy · Forwards auth routes to auth service · `api-gateway/src/services/authProxy.js`
- [Chat Proxy](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/api-gateway/src/services/chatProxy.js): proxy · Forwards chat routes to chat service · `api-gateway/src/services/chatProxy.js`

### Auth Service

Registration, login, and token flow

- [Auth Route](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.route.js): route layer · Registration, login, refresh endpoints · `auth-service/src/app/module/auth.route.js`
- [Auth Controller](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.controller.js): controller · HTTP handling for auth flows · `auth-service/src/app/module/auth.controller.js`
- [Auth Service](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.service.js): domain service · Token and credential logic · `auth-service/src/app/module/auth.service.js`
- [Auth Model](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/module/auth.model.js): mongo model · User and auth records · `auth-service/src/app/module/auth.model.js`
- [Auth DB](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/auth-service/src/app/config/db.js): mongo config · Auth database connection · `auth-service/src/app/config/db.js`

### Chat Service

Chat domain and async event publishing

- [Chat Routes](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/routes/message.routes.js): route layer · Message and group endpoints · `chat-service/src/routes/message.routes.js`
- [Chat Controllers](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/module/controllers/message.controller.js): controller layer · Group and message request handlers · `chat-service/src/module/controllers/message.controller.js`
- [Chat Service](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/module/services/message.service.js): domain service · Chat rules and persistence orchestration · `chat-service/src/module/services/message.service.js`
- [Message Event](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/module/events/message.producer.js): kafka producer · Publishes message events · `chat-service/src/module/events/message.producer.js`
- [Chat DB](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/config/db.js): mongo config · Chat database connection · `chat-service/src/config/db.js`

### Realtime

Socket.IO delivery and presence state

- [Socket Server](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/socket/socket.server.js): socket.io ingress · Realtime connection entry point · `socket-gateway/src/socket/socket.server.js`
- [Event Consumer](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/consumers/message.consumer.js): kafka consumer · Consumes chat events for delivery · `socket-gateway/src/consumers/message.consumer.js`
- [Presence Service](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/services/presence.service.js): state service · Online status and connection state · `socket-gateway/src/services/presence.service.js`
- [Socket Events](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/socket/socket.events.js): event mapping · Emits client-facing socket updates · `socket-gateway/src/socket/socket.events.js`

### Infrastructure

Shared local persistence and messaging

- [Redis](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/socket-gateway/src/config/redis.js): state store · Ephemeral presence storage · `socket-gateway/src/config/redis.js`
- [MongoDB](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/config/db.js): durable store · Persistent auth and chat data · `chat-service/src/config/db.js`
- [Kafka](https://github.com/tanvir-art/kafka_whatsapp_clone/blob/main/chat-service/src/config/kafka.js): event bus · Async message pipeline · `chat-service/src/config/kafka.js`

## Connections

- Client → API App: HTTP API · Client sends REST requests to the gateway
- Client → Socket Server: Socket.IO · Client connects directly for realtime features
- API App → Auth MW: guard · Gateway authenticates protected requests
- API App → Rate Limit: throttle · Gateway applies request limiting
- API App → Auth Proxy: /api/auth · Public auth routes are proxied internally
- API App → Chat Proxy: /api/chat · Public chat routes are proxied internally
- Auth Proxy → Auth Route: forward · Forwards auth requests to the auth service
- Chat Proxy → Chat Routes: forward · Forwards chat requests to the chat service
- Auth Route → Auth Controller: handle · Routes dispatch to controllers
- Auth Controller → Auth Service: delegate · Controllers invoke auth logic
- Auth Service → Auth Model: read/write · Auth service persists user records
- Auth Service → Auth DB: connect · Uses MongoDB connection
- Auth Service → MongoDB: persist · Stores durable auth data
- Chat Routes → Chat Controllers: handle · Routes dispatch to chat controllers
- Chat Controllers → Chat Service: delegate · Controllers invoke chat logic
- Chat Service → Chat DB: connect · Uses MongoDB connection
- Chat Service → MongoDB: persist · Stores conversations and messages
- Chat Service → Message Event: publish · Emits message events after writes
- Message Event → Kafka: produce · Sends chat events to Kafka
- Kafka → Event Consumer: consume · Socket gateway consumes message events
- Event Consumer → Socket Events: emit · Transforms backend events into socket updates
- Socket Events → Socket Server: deliver · Pushes updates to connected clients
- Socket Server → Presence Service: track · Updates presence around connections
- Presence Service → Redis: store · Persists ephemeral presence state
- Redis → Kafka: Indirect support for realtime subsystem