# gzydong/go-chat architecture

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

- Interactive diagram: https://gitdiagram.com/gzydong/go-chat
- Repository: https://github.com/gzydong/go-chat

## Overview

##### Project Type and Purpose
- Lumen-IM is a backend server for a web-based instant messaging (IM) system written in Go. It exposes HTTP APIs, runs a WebSocket (“comet”) server, processes asynchronous tasks via a queue, and schedules periodic jobs via cron.
- Key use cases: user authentication, one-to-one and group chat, file uploads, message recall/forward, group voting, system scheduling.

##### High-Level Architecture & Main Components
a. Clients
- Web frontend (separate repo) communicates over HTTP(S) and WebSocket.
b. HTTP API Server (cmd/lumenim http)
- internal/apis – REST handlers for admin, open and web namespaces.
- internal/business & internal/service – business logic and orchestration.
- internal/repository – MySQL/Redis data access.
- internal/provider – external integrations (Minio, email, captcha, OpenAI).
- config & resource – app configuration and templates.
c. Comet (cmd/lumenim comet)
- internal/comet – WebSocket server, real-time message routing, NSQ consumers for chat events, subscriber management.
d. Queue Worker (cmd/lumenim queue)
- internal/mission/queue and internal/comet/consume – asynchronous job producers/consumers using NSQ.
e. Crontab Scheduler (cmd/lumenim crontab)
- internal/mission/cron – scheduled cleanup, maintenance tasks.
f. Shared Core Libraries (internal/pkg)
- core server abstractions, middleware, socket adapters, validators, logging, error handling, utilities.
g. Infrastructure
- MySQL – persistent storage
- Redis – caching, session/state management
- NSQ – message queue for async events
- Minio – object storage for file uploads

##### Component Interactions and Data Flows
- HTTP request → router → handler → service → repository → MySQL/Redis → response
- WebSocket client connects → comet router → event handler → service → publishes to NSQ or writes to Redis → comet broadcast back to clients
- Business logic emits jobs to NSQ → queue worker consumes and updates database/Redis or publishes further events
- Cron scheduler triggers tasks → mission handlers perform cleanup or periodic database/Redis operations
- All layers wired via Google Wire (cmd/lumenim/wire.go, internal/*/wire.go)

##### Architectural Patterns & Principles
- Layered (Onion/Hexagonal) architecture:
Presentation (handlers) → Application (services) → Domain (business) → Infrastructure (repositories/providers)
- Dependency Injection via Wire for testability and clear component boundaries.
- Event-driven components communicating via NSQ for decoupling.
- Micro-process model: separate processes for HTTP, WebSocket, queue, cron.
- Protobuf definitions under api/proto and generated Go files in api/pb for internal/open/admin API contracts or future gRPC endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% HTTP API Server
    subgraph "HTTP API Server" 
        direction TB
        API_Main["cmd/lumenim/main.go"]:::api
        API_Handlers["internal/apis/"]:::handler
        API_Services["internal/service & internal/business"]:::service
        API_RepoProv["internal/repository & internal/provider"]:::repo
        API_Config["config/ & internal/resource/"]:::config
    end

    %% Comet Server
    subgraph "Comet Server"
        direction TB
        Comet_Wire["internal/comet/wire.go"]:::comet
        Comet_Server["internal/comet/server.go"]:::comet
        Comet_Router["internal/comet/router/route.go"]:::handler
        Comet_Handler["internal/comet/handler/"]:::service
        Comet_Process["internal/comet/process/"]:::service
        Comet_Consume["internal/comet/consume/"]:::repo
    end

    %% Queue Worker
    subgraph "Queue Worker"
        direction TB
        Queue_Wire["internal/mission/queue/wire.go"]:::queue
        Queue_Producer["internal/mission/queue/"]:::service
        Queue_Consumer["internal/comet/consume/"]:::repo
    end

    %% Cron Scheduler
    subgraph "Cron Scheduler"
        direction TB
        Cron_Wire["internal/mission/cron/wire.go"]:::cron
        Cron_Tasks["internal/mission/cron/"]:::service
        Cron_Main["internal/mission/crontab.go"]:::cron
    end

    %% Shared Core Libraries
    subgraph "Shared Core Libraries"
        direction TB
        Shared_PKG["internal/pkg/"]:::core
    end

    %% External Infrastructure
    subgraph "Infrastructure"
        direction TB
        MySQL[(MySQL)]:::external
        Redis[(Redis)]:::external
        NSQ[(NSQ)]:::external
        Minio[(Minio)]:::external
        Ext_Services[(Email/Captcha/OpenAI)]:::external
    end

    %% Clients
    Client_HTTP["Web Frontend (HTTP)"]:::client
    Client_WS["Web Frontend (WebSocket)"]:::client

    %% Flows HTTP API
    Client_HTTP -->|JSON/HTTP| API_Main
    API_Main --> API_Handlers
    API_Handlers -->|calls| API_Services
    API_Services -->|data access| API_RepoProv
    API_RepoProv --> MySQL
    API_RepoProv --> Redis
    API_Handlers -->|loads config| API_Config
    API_Handlers --> Shared_PKG

    %% Flows Comet
    Client_WS -->|WebSocket| Comet_Server
    Comet_Server --> Comet_Router
    Comet_Router --> Comet_Handler
    Comet_Handler --> Comet_Process
    Comet_Process -->|publish/subscribe| NSQ
    Comet_Process --> Redis
    Comet_Consume -.->|consumes events| NSQ
    Comet_Process --> Shared_PKG

    %% Flows Queue
    Comet_Handler -->|produce job| Queue_Producer
    Queue_Producer --> NSQ
    NSQ -.-> Queue_Consumer
    Queue_Consumer --> API_RepoProv
    Queue_Consumer --> Shared_PKG

    %% Flows Cron
    Cron_Main --> Cron_Tasks
    Cron_Tasks --> API_RepoProv
    Cron_Tasks --> Redis
    Cron_Tasks --> Shared_PKG

    %% Infra to providers
    API_RepoProv --> Minio
    API_RepoProv --> Ext_Services
    Shared_PKG --> Ext_Services

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Handlers"]:::handler
        L2["Services"]:::service
        L3["Repositories/Providers"]:::repo
        L4["Config/Resources"]:::config
        L5["Core Libraries"]:::core
        L6["HTTP API"]:::api
        L7["Comet"]:::comet
        L8["Queue"]:::queue
        L9["Cron"]:::cron
        L10["External"]:::external
        L11["Clients"]:::client
    end

    %% Click Events
    click API_Main "https://github.com/gzydong/go-chat/blob/master/cmd/lumenim/main.go"
    click API_Handlers "https://github.com/gzydong/go-chat/tree/master/internal/apis/"
    click API_Services "https://github.com/gzydong/go-chat/tree/master/internal/service/"
    click API_Services "https://github.com/gzydong/go-chat/tree/master/internal/business/"
    click API_RepoProv "https://github.com/gzydong/go-chat/tree/master/internal/repository/"
    click API_RepoProv "https://github.com/gzydong/go-chat/tree/master/internal/provider/"
    click API_Config "https://github.com/gzydong/go-chat/tree/master/config/"
    click API_Config "https://github.com/gzydong/go-chat/tree/master/internal/resource/"

    click Comet_Wire "https://github.com/gzydong/go-chat/blob/master/internal/comet/wire.go"
    click Comet_Server "https://github.com/gzydong/go-chat/blob/master/internal/comet/server.go"
    click Comet_Router "https://github.com/gzydong/go-chat/blob/master/internal/comet/router/route.go"
    click Comet_Handler "https://github.com/gzydong/go-chat/tree/master/internal/comet/handler/"
    click Comet_Process "https://github.com/gzydong/go-chat/tree/master/internal/comet/process/"
    click Comet_Consume "https://github.com/gzydong/go-chat/tree/master/internal/comet/consume/"

    click Queue_Wire "https://github.com/gzydong/go-chat/blob/master/internal/mission/queue/wire.go"
    click Queue_Producer "https://github.com/gzydong/go-chat/tree/master/internal/mission/queue/"
    click Queue_Consumer "https://github.com/gzydong/go-chat/tree/master/internal/comet/consume/"

    click Cron_Wire "https://github.com/gzydong/go-chat/blob/master/internal/mission/cron/wire.go"
    click Cron_Tasks "https://github.com/gzydong/go-chat/tree/master/internal/mission/cron/"
    click Cron_Main "https://github.com/gzydong/go-chat/blob/master/internal/mission/crontab.go"

    click Shared_PKG "https://github.com/gzydong/go-chat/tree/master/internal/pkg/"

    %% Styles
    classDef handler fill:#D0E8FF,stroke:#5B9BD5
    classDef service fill:#DFF2D8,stroke:#6AA84F
    classDef repo fill:#FFF2CC,stroke:#E69138
    classDef config fill:#FDE9D9,stroke:#C0504D
    classDef core fill:#EDEDED,stroke:#7F7F7F
    classDef api fill:#BDD7EE,stroke:#2E75B6
    classDef comet fill:#D9EAD3,stroke:#38761D
    classDef queue fill:#F9CB9C,stroke:#B45F06
    classDef cron fill:#D9D2E9,stroke:#674EA7
    classDef external fill:#F4CCCC,stroke:#CC0000
    classDef client fill:#FFF2CC,stroke:#BF9000
```
