# aceld/zinx architecture

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

- Interactive diagram: https://gitdiagram.com/aceld/zinx
- Repository: https://github.com/aceld/zinx

## Overview

##### Project type and purpose
- This is “Zinx,” a Golang-based, lightweight concurrent TCP-server framework.
- It provides core modules for building long-linked services (games, message routers, etc.), plus hooks for middleware, async operations, logging, timers, and configuration.

##### File structure
- Top-level “znet” folder: core server components (Server, Connection, ConnManager, Router, MsgHandler, WorkerPool).
- “ziface”: all interfaces (IConnection, IServer, IRequest, IRouter, IDecoder, IDataPack, IInterceptor, IClient, etc.).
- “zpack”: message framing (TLV/LTV packers).
- “zdecoder”: CRC and TLV decoders.
- “zinterceptor”: interceptor chain for pipeline processing.
- “zasync_op”: asynchronous-task engine.
- “znotify”: publish/subscribe notifications.
- “ztimer”: delay/timer scheduler.
- “zconf”: configuration loader.
- “zlog”: pluggable logging core.
- “zutils”: common utilities (UUID, locks, hashing).
- “examples/…” and “zinx_app_demo/…” host sample servers/clients illustrating framework use.

##### README for architecture
- Describes server startup, connection hooks, router registration, message dispatch, worker pools.

##### Elements
- Clear labels for each package/component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Client["External Client"]:::external
    ExampleApp["Example App / Business Code"]:::external

    %% Core Server Layer
    subgraph "Core Server" 
        Server["znet.Server"]:::core
        ConnManager["ConnManager"]:::core
        Connection["Connection"]:::core
        MsgHandler["MsgHandler"]:::core
        Router["Router (IRouter)"]:::core
        WorkerPool["Worker Pool"]:::core
    end

    %% Framing & Decoding
    subgraph "Framing & Decoding" 
        DataPack["DataPack"]:::middleware
        Decoder["Decoder"]:::middleware
    end

    %% Interceptor Chain
    subgraph "Interceptor Chain" 
        InterceptorChain["Interceptor Chain"]:::middleware
    end

    %% Async / Notify / Timer
    subgraph "Extensions"
        AsyncOp["Async-Op Engine"]:::ext
        Notify["Notification Bus"]:::ext
        Timer["Timer / Scheduler"]:::ext
    end

    %% Configuration & Logging & Utilities
    subgraph "Infrastructure"
        Config["Config Loader"]:::infra
        Log["Logging Module"]:::infra
        Utils["Utilities"]:::infra
    end

    %% Connections
    Client -->|"TCP Accept"| Server
    Server -->|Creates| Connection
    Server -->|Registers| ConnManager
    Connection -->|"ReadLoop raw bytes"| DataPack
    DataPack -->|"Unpack frame"| Decoder
    Decoder -->|"Decode message"| InterceptorChain
    InterceptorChain -->|"Process pipeline"| MsgHandler
    MsgHandler -->|"Enqueue task"| WorkerPool
    WorkerPool -->|"Handle(request)"| Router
    Router -->|"Business logic"| ExampleApp
    ExampleApp -->|"Return response"| Router
    Router -->|Dispatch async tasks| AsyncOp
    Router -->|Publish events| Notify
    Server -->|Schedule timers| Timer
    Config -->|Init parameters| Server
    Log -.->|Structured logging| Server
    Log -.->|Structured logging| Connection
    Log -.->|Structured logging| MsgHandler
    Utils -.->|Helpers| Server

    %% Response path
    Router -->|"Pack & send"| DataPack
    DataPack -->|"Write to"| Connection
    Connection -->|Return data| Client

    %% Click Events
    click Server "https://github.com/aceld/zinx/blob/master/znet/server.go"
    click ConnManager "https://github.com/aceld/zinx/blob/master/znet/connmanager.go"
    click Connection "https://github.com/aceld/zinx/blob/master/znet/connection.go"
    click DataPack "https://github.com/aceld/zinx/blob/master/zpack/packfactory.go"
    click Decoder "https://github.com/aceld/zinx/blob/master/zdecoder/tlvdecoder.go"
    click InterceptorChain "https://github.com/aceld/zinx/blob/master/zinterceptor/chain.go"
    click MsgHandler "https://github.com/aceld/zinx/blob/master/znet/msghandler.go"
    click Router "https://github.com/aceld/zinx/blob/master/znet/router.go"
    click AsyncOp "https://github.com/aceld/zinx/blob/master/zasync_op/async_op.go"
    click Notify "https://github.com/aceld/zinx/blob/master/znotify/notify.go"
    click Timer "https://github.com/aceld/zinx/blob/master/ztimer/timer.go"
    click Config "https://github.com/aceld/zinx/blob/master/zconf/zconf.go"
    click Log "https://github.com/aceld/zinx/blob/master/zlog/logger_core.go"
    click Utils "https://github.com/aceld/zinx/blob/master/zutils/snowflake_uuid.go"
    click ExampleApp "https://github.com/aceld/zinx/tree/master/zinx_app_demo/mmo_game/"

    %% Styles
    classDef external fill:#FFFBCC,stroke:#AAA,stroke-width:1px
    classDef core fill:#B3D4FC,stroke:#1E90FF,stroke-width:2px
    classDef middleware fill:#D5E8D4,stroke:#82B366,stroke-width:2px
    classDef ext fill:#F8CECC,stroke:#B85450,stroke-width:2px
    classDef infra fill:#E1D5E7,stroke:#9673A6,stroke-width:2px
```
