# kimchanho97/sunsuwedding_chat architecture

> Architecture diagram of the GitHub repository kimchanho97/sunsuwedding_chat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kimchanho97/sunsuwedding_chat
- Repository: https://github.com/kimchanho97/sunsuwedding_chat

## Overview

##### Project Type and Purpose
- It is a **backend service** for a real-time chat application built on Spring Boot.
- Core responsibilities:
- Handle WebSocket/STOMP connections for chat & presence.
- Publish/consume Kafka events for asynchronous processing.
- Maintain three data stores (Redis, MongoDB, RDB) for real-time metadata, message history, and structured relational data.
- Expose internal and external REST APIs for integration.

##### File Structure
- **Top-level**: Dockerfile, Gradle build, deploy scripts → containerized, CI/CD ready.
- **src/main/java/com/sunsuwedding/chat**:
- **controller**: external (REST), internal (service-to-service), websocket handlers.
- **service**: business logic.
- **kafka**: producer & consumer layers.
- **redis**, **repository**, **model**: data access & domain.
- **config**: Kafka, Redis, WebSocket, MVC, etc.
- **client** packages contain HTTP/REST clients (inter-server & external).
- **scheduler**: batch sync tasks for eventual consistency.

##### Key Insights from README
- **Tri-store architecture**: Redis for real-time, MongoDB for messages, RDB for chat room metadata.
- **Event streaming pipeline**: multi-stage Kafka topics for message ingestion, persistence, read-sync, room sorting.
- **Unicast message delivery**: using Redis to route WebSocket messages to specific server instance.
- **Reliability guarantees**: combined at-least-once & exactly-once via Kafka transactions and idempotent consumers.

##### Main Components
a. **Clients**: Web/Native clients connecting via STOMP/WebSocket and REST.
b. **Load Balancer** (L4/L7): Distributes WebSocket and HTTP connections to Chat Server instances.
c. **Chat Server Cluster** (Spring Boot instances):
- **REST API Layer** (external/internal controllers)
- **WebSocket/STOMP Layer** (ChatWebSocketController, PresenceWebSocketController)
- **Service Layer** (ChatRoomService, PresenceService, etc.)
- **Kafka Producers/Consumers**
- **Scheduler** (batch sync jobs)
d. **Kafka Cluster**: Topics (chat-message, chat-message-saved, read-sync, resort-batch, presence-unicast, etc.)
e. **Redis Cluster**:
- Presence routing (chat:presence:…)
- Metadata (chat:room:meta:…), user room lists, dirty keys, sequences
f. **MongoDB Cluster**: message documents (ChatMessageDocument)
g. **RDB (MySQL/Postgres)**: chat rooms, participants, transactional metadata
h. **S3 / Blob Storage** (optional): for image uploads (ChatImageUploadClient)
i. **Deployment Infrastructure**: Docker, docker-compose, CI/CD pipeline (GitHub Actions → deploy.sh)

##### Relationships and Data Flows
1. Client ↔ Load Balancer ↔ Chat Server (WebSocket / REST)
2. Chat Server REST endpoints publish Kafka events (chat-message)
3. Kafka → Chat Server consumers → Redis (routing, read-sync, dirty keys) → other Chat Servers via WebSocket
4. Chat Server consumer → MongoDB (persist message) → publish chat-message-saved topic
5. Chat-message-saved consumer → update Redis metadata, schedule batch RDB sync
6. Scheduler → fetch dirty keys from Redis → batch JDBC update to RDB

##### Architectural Patterns
- **Layered Architecture**: API (controllers) → Service → Data/Event layer
- **Event-Driven**: Kafka topics decouple ingestion, persistence, fan-out
- **Cache Aside / Write-Through** with Redis
- **Tri-store**: real-time vs. persistent vs. relational
- **Unicast Routing**: Redis-based location lookup for WebSocket messages
- **Batch Synchronization**: eventual consistency between Redis and RDB

##### Diagramming Conventions
- Use **rectangles** for compute components (Load Balancer, Chat Servers, Scheduler)
- Blue for frontend/client/entry points
- Green for Chat Server internals
- Orange for event bus (Kafka)
- Yellow for Redis cache
- Purple for MongoDB
- Gray for RDB

##### Detail Without Over-Segmentation
- Major components and their interactions.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients and Entry
    Clients("Clients\n(Web/Native)"):::frontend
    LoadBalancer("Load Balancer"):::infra
    Clients --> LoadBalancer
    click LoadBalancer "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/deploy/docker-compose.yml"

    %% Chat Server Cluster
    subgraph "Chat Server Cluster" 
        direction TB
        App("ChatApplication"):::backend
        click App "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/ChatApplication.java"

        subgraph Controllers
            direction TB
            RESTEx("External REST Controllers"):::backend
            click RESTEx "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/controller/external"
            RESTIn("Internal REST Controllers"):::backend
            click RESTIn "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/controller/internal"
            WS("WebSocket/STOMP Controllers"):::backend
            click WS "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/controller/websocket"
        end

        Services("Service Layer"):::backend
        click Services "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/service"

        subgraph KafkaLayer
            direction TB
            KP("Kafka Producer Layer"):::bus
            click KP "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/kafka/producer"
            KC("Kafka Consumer Layer"):::bus
            click KC "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/kafka/consumer"
        end

        Scheduler("Scheduler\n(Batch Sync Jobs)"):::backend
        click Scheduler "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/scheduler/ChatDataBatchSyncScheduler.java"

        subgraph Config
            direction TB
            RedisCfg("RedisConfig"):::backend
            click RedisCfg "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/config/RedisConfig.java"
            KafkaCfg("KafkaProducerConfig,\nKafkaConsumerConfig,\nKafkaTopicConfig"):::backend
            click KafkaCfg "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/config/KafkaProducerConfig.java"
            WSConfig("WebSocketConfig"):::backend
            click WSConfig "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/config/WebSocketConfig.java"
        end

        Common("Common Utilities & Exceptions"):::backend
        click Common "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/common"
        HTTPClients("HTTP Clients\n(incl. S3 Upload)"):::backend
        click HTTPClients "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/client"
        
        %% Internal Flows
        LoadBalancer --> App
        App --> RESTEx
        App --> RESTIn
        App --> WS
        RESTEx --> KP
        RESTIn --> KP
        WS --> Services
        Services --> KP
        KC --> Services
        Scheduler --> RedisAbs
    end

    %% Event Bus
    subgraph "Kafka Cluster" 
        direction TB
        chatMsg("chat-message"):::bus
        chatSaved("chat-message-saved"):::bus
        readSync("read-sync"):::bus
        resortBatch("resort-batch"):::bus
        presenceUni("presence-unicast"):::bus
    end

    KP --> chatMsg
    chatMsg --> KC
    KC --> chatSaved
    chatSaved --> KC
    KC --> readSync
    KC --> resortBatch
    KC --> presenceUni

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Redis("Redis Cluster"):::cache
        RedisAbs("Redis Abstractions\n(routing & metadata)"):::cache
        click RedisAbs "https://github.com/kimchanho97/sunsuwedding_chat/tree/main/src/main/java/com/sunsuwedding/chat/redis"
        Mongo("MongoDB Cluster"):::db
        MongoModel("ChatMessageDocument"):::db
        click MongoModel "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/model/ChatMessageDocument.java"
        MongoRepo("ChatMessageMongoRepository"):::db
        click MongoRepo "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/repository/ChatMessageMongoRepository.java"
        RDB("RDB Cluster\n(MySQL/Postgres)"):::rdb
        RDBModel("ChatRoomMeta"):::rdb
        click RDBModel "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/src/main/java/com/sunsuwedding/chat/model/ChatRoomMeta.java"
    end

    KC --> Redis
    KC --> Mongo
    KC --> RDB
    chatSaved --> Mongo
    chatSaved --> KC
    Services --> Redis
    Services --> MongoRepo
    Services --> RDBModel
    presenceUni --> RedisAbs
    RedisAbs --> WS
    Redis --> Scheduler
    Scheduler --> RDB

    %% Optional S3
    S3("S3 / Blob Storage"):::infra
    HTTPClients --> S3

    %% Deployment Infrastructure
    GH("GitHub Actions"):::infra
    click GH "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/.github/workflows/deploy.yml"
    DeploySh("Deploy Script"):::infra
    click DeploySh "https://github.com/kimchanho97/sunsuwedding_chat/blob/main/deploy/deploy.sh"
    GH --> DeploySh

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef bus fill:#FFA500,stroke:#333,stroke-width:1px
    classDef cache fill:#FFFF00,stroke:#333,stroke-width:1px
    classDef db fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef rdb fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef infra fill:#C0C0C0,stroke:#333,stroke-width:1px
```
