# terry-mao/goim architecture

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

- Interactive diagram: https://gitdiagram.com/terry-mao/goim
- Repository: https://github.com/terry-mao/goim

## Overview

##### Main Architectural Components
- Comet Module:
- Found in both the cmd/comet and internal/comet directories.
- Acts as the gateway server handling client connections (via WebSocket, TCP, HTTP) and managing connection lifecycle, heartbeats, and client authentication.

- Logic Module:
- Its code is in cmd/logic and internal/logic.
- Responsible for core business logic, routing, online user tracking, and possibly load balancing.
- Uses defined gRPC and HTTP endpoints (as seen from the presence of subdirectories like “grpc” and “http” within internal/logic).

- Job Module:
- Shown in cmd/job and internal/job.
- Handles asynchronous push notifications and works in tandem with Kafka, as indicated by references in internal/job and README dependency notes.

- API Definitions:
- The api folder holds protobuf (.proto) files for comet, logic, and protocol definitions.
- These define the standardized API interfaces used by the modules to interact (e.g., over gRPC).

- Supporting Components and Utilities:
- There are several common code modules in the pkg directory (bufio, bytes, encoding, etc.) which are utilities used throughout the services.

- Benchmarks & Examples:
- Benchmarks (in benchmarks directory) and examples (in examples) are included for performance testing and client demos.
- These can be noted as “Benchmark Tools” and “Client/Example Applications” if needed for context, especially if they demonstrate client-server interaction.

##### Relationships and Interactions
- Client Applications connect to the Comet service.
- Comet service uses the Protocol API (via gRPC and possibly REST) to communicate with the Logic service.
- Logic service handles authentication, routing, and state management and may also call back to Comet if necessary.
- The Job service interacts with Kafka for asynchronous message processing and push notifications.
- That API libraries (via protobuf definitions) are shared across these microservices.

- That the system supports multiple protocols (WebSocket, TCP, HTTP) on the client-to-comet level.

##### Architectural Patterns and Design Principles
- The system follows a modular microservices-like architecture: distinct services for connection gateway, business logic, and asynchronous job handling.
- The use of API/protobuf files signals a focus on strong interface definitions and decoupled service interactions.
- Scalability is emphasized through “unlimited dynamic job and logic modules.” Mention that the architecture supports horizontal scaling.

##### Technologies and Frameworks
- Go is the primary language (as shown in README and file tree).
- gRPC for inter-service communication (refer to grpc directories and protobuf files).
- HTTP and WebSocket protocols for client communication.
- Kafka for asynchronous push notifications in the Job module.
- Additional internal packages showing custom implementations (buffer management, time utilities, etc.) can be noted as supporting technologies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    Clients("Clients"):::client
    Comet("Comet Service"):::comet
    Logic("Logic Service"):::logic
    Job("Job Service / Async Push"):::job
    Kafka("Message Broker (Kafka)"):::kafka
    API("API/Protobuf Interface Definitions"):::api
    Util("Common Utilities / Libraries"):::util
    Bench("Benchmark Tools"):::bench
    Demo("Client/Example Applications"):::demo

    %% Flow Connections
    Clients -->|"WebSocket/TCP/HTTP"| Comet
    Comet <-->|"gRPC/HTTP"| Logic
    Logic -->|"AsyncTasks"| Job
    Job -->|"PushNotifications"| Kafka

    %% Shared API usage
    Comet ---|"uses"| API
    Logic ---|"uses"| API
    Job ---|"uses"| API

    %% Utilities support (dashed)
    Comet -.->|"helpers"| Util
    Logic -.->|"helpers"| Util
    Job -.->|"helpers"| Util

    %% Benchmarks and Demo connections (for context)
    Clients ---|"test/demo"| Demo
    Demo ---|"simulate load"| Comet
    Bench ---|"performance"| Comet

    %% Click Events
    click Comet "https://github.com/terry-mao/goim/tree/master/cmd/comet"
    click Comet "https://github.com/terry-mao/goim/tree/master/internal/comet"
    click Logic "https://github.com/terry-mao/goim/tree/master/cmd/logic"
    click Logic "https://github.com/terry-mao/goim/tree/master/internal/logic"
    click Job "https://github.com/terry-mao/goim/tree/master/cmd/job"
    click Job "https://github.com/terry-mao/goim/tree/master/internal/job"
    click API "https://github.com/terry-mao/goim/tree/master/api"
    click Util "https://github.com/terry-mao/goim/tree/master/pkg"
    click Bench "https://github.com/terry-mao/goim/tree/master/benchmarks"
    click Demo "https://github.com/terry-mao/goim/tree/master/examples"

    %% Class Definitions for Colors
    classDef client fill:#bebada,stroke:#8a2be2,stroke-width:2px;
    classDef comet fill:#a6cee3,stroke:#1f78b4,stroke-width:2px;
    classDef logic fill:#b2df8a,stroke:#33a02c,stroke-width:2px;
    classDef job fill:#fb9a99,stroke:#e31a1c,stroke-width:2px;
    classDef kafka fill:#cab2d6,stroke:#6a3d9a,stroke-width:2px;
    classDef api fill:#fdbf6f,stroke:#ff7f00,stroke-width:2px;
    classDef util fill:#ffff99,stroke:#ffd700,stroke-width:2px;
    classDef bench fill:#f0e442,stroke:#ff8c00,stroke-width:2px;
    classDef demo fill:#8dd3c7,stroke:#2ca02c,stroke-width:2px;
```
