Chat system design

chat-system-design.md

Architecture Overview

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Client Apps    │◄────┤  WebSockets  │────►│  Chat Service   │
└─────────────────┘     └──────────────┘     └────────┬────────┘
                                                      │
                                                      ▼
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Group Service  │◄────┤     NATS     │◄────┤ Message Service │
└─────────────────┘     └──────────────┘     └─────────────────┘
        │                      ▲                      │
        └──────────────────────┼──────────────────────┘
                               │
                     ┌─────────────────┐
                     │  Databases/     │
                     │  Persistence    │
                     └─────────────────┘

Detailed Flow Diagrams

New Message Notification Flow

┌──────────┐     ┌──────────┐     ┌──────────────┐     ┌───────────────┐
│ User A   │────►│WebSocket │────►│ Chat Service │────►│ Message Saved │
│ (Sender) │     │ Gateway  │     │              │     │ to Database   │
└──────────┘     └──────────┘     └──────┬───────┘     └───────────────┘
                                         │
                                         ▼
                                   ┌────────────────┐
                                   │  NATS Event    │
                                   │chat.message.new│
                                   └───────┬────────┘
                                           │
                                           ▼
┌───────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Push Notif.  │◄────┤  Notification    │◄────┤ Chat Event      │
│  Provider     │     │  Service         │     │ Listener        │
└───────────────┘     └──────────────────┘     └─────────────────┘
                                │
                                ▼
                      ┌────────────────────┐
                      │  Notification      │
                      │  Saved to Database │
                      └──────────┬─────────┘
                                 │
                                 ▼
                      ┌────────────────────┐
                      │  NATS Event        │
                      │notification.new    │
                      └──────────┬─────────┘
                                 │
                                 ▼
┌──────────┐     ┌──────────┐    │    ┌─────────────┐
│ User B   │◄────┤WebSocket │◄────────┤ Mobile Push │
│(Recipient)│    │ Gateway  │         │ Service     │
└──────────┘     └──────────┘         └─────────────┘

Group Invitation Notification Flow

┌────────────┐     ┌────────────┐     ┌────────────────┐
│ Group Admin│────►│ REST API   │────►│ Group Service  │
└────────────┘     └────────────┘     └───────┬────────┘
                                              │
                                              ▼
                                     ┌────────────────┐
                                     │ Group Updated  │
                                     │ in Database    │
                                     └───────┬────────┘
                                             │
                                             ▼
                                     ┌───────────────────┐
                                     │  NATS Event       │
                                     │group.members.added│
                                     └──────┬────────────┘
                                            │
          ┌───────────────────────────┬─────┴─────┬──────────────────────┐
          ▼                           ▼           ▼                      ▼
┌─────────────────┐          ┌───────────────┐    │             ┌────────────────┐
│ Chat Event      │          │ WebSocket     │    │             │ Notification   │
│ Listener        │          │ Gateway       │    │             │ Service        │
└────────┬────────┘          └───────┬───────┘    │             └────────┬───────┘
         │                           │            │                      │
         ▼                           ▼            │                      ▼
┌─────────────────┐          ┌───────────────┐    │             ┌────────────────┐
│ Notification    │          │ Group Members │    │             │ Push/Email     │
│ Created         │          │ notified via  │    │             │ Notifications  │
└────────┬────────┘          │ WebSockets    │    │             │ Sent           │
         │                   └───────────────┘    │             └────────────────┘
         │                                        │
         │                                        ▼
         │                               ┌────────────────┐
         │                               │ New Members    │
         │                               │ Join Group     │
         │                               └────────────────┘
         ▼
┌─────────────────┐
│ Notification    │
│ Stored in DB    │
└─────────────────┘

Read Receipt and Notification Status Flow

┌──────────┐     ┌──────────┐     ┌────────────────┐
│ User     │────►│WebSocket │────►│ Read Receipt   │
│          │     │ Gateway  │     │ Handler        │
└──────────┘     └──────────┘     └───────┬────────┘
                                          │
                                          ▼
                                   ┌──────────────┐
                                   │   Update     │
                                   │ Message/Notif│
                                   │ In Database  │
                                   └───────┬──────┘
                                           │
                                           ▼
                                   ┌─────────────────┐
                                   │  NATS Event     │
                                   │notification.read│
                                   │  or             │
                                   │chat.message.read│
                                   └──────┬──────────┘
                                          │
                   ┌─────────────────┬────┴────┬─────────────────┐
                   ▼                 ▼         ▼                 ▼
           ┌───────────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────┐
           │ WebSocket     │ │ Chat      │ │ Group     │ │ Notification  │
           │ Gateway       │ │ Service   │ │ Service   │ │ Service       │
           └───────┬───────┘ └───────────┘ └───────────┘ └───────────────┘
                   │
                   ▼
           ┌───────────────┐
           │ All Connected │
           │ User Devices  │
           │ Synchronized  │
           └───────────────┘