# sylar-yin/sylar architecture

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

- Interactive diagram: https://gitdiagram.com/sylar-yin/sylar
- Repository: https://github.com/sylar-yin/sylar

## Overview

##### Project Type and Purpose
- Type: A C++ high-performance, full-featured server framework / library.
- Purpose: Provide building blocks (logging, configuration, threading, coroutine scheduling, I/O multiplexing, networking, protocol implementations, ORM, etc.) so that developers can rapidly assemble custom servers (HTTP, WebSocket, RPC, etc.) and services.

##### File Structure
- Top-level:
- bin/conf: YAML configs for logs, server, system, database, etc.
- cmake: build helper scripts.
- examples, samples, template: demonstration servers and module templates.
- sylar: core framework code, organized into subdirectories (db, ds, email, fiber, http, iomanager, module, orm, rock, streams, util, worker, zk_client, etc.).
- tests: unit tests covering each module.
- Architectural hints:
- Core modules: application lifecycle, module/plugin system (sylar/application*, module*).
- Concurrency: thread abstraction, fiber (user‐level threads), scheduler, I/O manager.
- Networking: Socket, Stream, TCPServer, HTTPServer/Client, WebSocket.
- Protocol libraries: HTTP/1.1, WebSocket, custom rock RPC, name server (ns).
- Utilities: logging, configuration, serialization (ByteArray), data structures, cryptography, JSON, URI parsing.
- Persistence: database drivers for MySQL, SQLite3, Redis; ORM layer.
- External services: Zookeeper client, SMTP email, service discovery, load balancing.

##### Read README for Insights
- Modules described sequentially: logging, config, threading, coroutine, scheduler, I/O scheduler (epoll), hook, socket, ByteArray, TCPServer, Stream, HTTP, Servlet.
- Emphasis on N:M coroutine scheduling, Reactor pattern via epoll, finite‐state‐machine HTTP parsing (Ragel), pluggable servlets.

##### Main Components and Their Interactions
a. Core Framework Layer
- Logger & Config (static, global singletons)
- Thread & Synchronization primitives
- Fiber (coroutine) abstraction
- Scheduler (N threads ↔ M fibers)
- Hook layer (shim for blocking syscalls to nonblocking)
- I/O Manager (epoll-based Reactor with timed events)
b. Networking Layer
- Socket abstractions (Address, Socket)
- Stream abstractions (AsyncSocketStream)
- TCPServer (accept loop, connection dispatch)
- HTTPServer / HTTPClient (based on TCPServer + HTTP protocol)
- WebSocket support
- Custom RPC protocols: rock, ns (name server)
c. Data & Persistence Layer
- ByteArray (binary serialization)
- Database drivers (MySQL, SQLite3, Redis)
- ORM (table/column/index abstraction)
- Zookeeper client for service discovery
d. Application Layer
- Module mechanism (plugins derived from IModule)
- Example modules (status servlet, config servlet)
- User‐defined servers (examples/ and template/)

e. External Dependencies
- YAML (for config)
- Ragel (for HTTP parser)
- POSIX threads, epoll
- Third-party libs: MySQL client, hiredis, SQLite3, zookeeper C

##### Architectural Patterns & Principles
- Reactor (epoll in I/O Manager)
- Proactor via coroutine scheduling + hook shim
- N:M coroutine scheduling (user-level threads over OS threads)
- Singleton & Module plugin pattern for extensibility
- Layered architecture: Core → Networking → Protocols → Applications
- Separation of concerns: logging/config separate from runtime; protocol-specific code separate from transport.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Layer 1: Infrastructure"
        OS["OS (pthreads, epoll)"]:::external
    end

    subgraph "Layer 2: Core Framework"
        Logger["Logger"]:::core
        Config["Config"]:::core
        Thread["Thread"]:::core
        Mutex["Mutex"]:::core
        Fiber["Fiber"]:::core
        Scheduler["Scheduler"]:::core
        Hook["Hook"]:::core
        IOManager["I/O Manager"]:::core
    end

    subgraph "Layer 3: Transport"
        Address["Address"]:::networking
        Socket["Socket"]:::networking
        Stream["Base Stream"]:::networking
        AsyncStream["AsyncSocketStream"]:::networking
        TCPServer["TCPServer"]:::networking
    end

    subgraph "Layer 4: Protocols"
        HTTPServer["HTTPServer/Client"]:::protocol
        WebSocket["WebSocket"]:::protocol
        RockRPC["Rock RPC"]:::protocol
        NameServer["NameServer"]:::protocol
    end

    subgraph "Layer 5: Data & Persistence"
        ByteArray["ByteArray"]:::data
        MySQLDriver["MySQL Driver"]:::data
        SQLiteDriver["SQLite3 Driver"]:::data
        RedisDriver["Redis Driver"]:::data
        FoxThread["DB Pool (FoxThread)"]:::data
        ORM["ORM Layer"]:::data
        ZKClient["Zookeeper Client"]:::data
    end

    subgraph "Layer 6: Application"
        Application["Application"]:::app
        ModuleSystem["Module System"]:::app
        Daemon["Daemon Entry"]:::app
        ExampleModules["Example Servlets & Modules"]:::app
        UserServers["User Servers (examples/)"]:::app
    end

    subgraph "External Services"
        DBService["MySQL/Redis/SQLite"]:::external
        ZKService["Zookeeper"]:::external
        SMTPService["SMTP Email"]:::external
    end

    subgraph "Build & Config Artifacts"
        CMake["CMake Scripts"]:::build
        Conf["YAML Configs"]:::build
    end

    %% Core dependencies
    Config -->|reads settings| Logger
    Config -->|reads settings| Thread
    Config -->|reads settings| Fiber
    Config -->|reads settings| Scheduler
    Config -->|reads settings| IOManager

    Thread -->|spawns| Fiber
    Scheduler -->|schedules| Fiber
    Scheduler -->|dispatches I/O tasks| IOManager
    Hook -->|shims blocking calls| IOManager
    IOManager -->|uses epoll| OS

    %% Transport flow
    IOManager -->|events| Socket
    Socket -->|wraps| Address
    Socket -->|provides| Stream
    Stream -->|specialized| AsyncStream
    AsyncStream -->|drives| TCPServer

    TCPServer -->|hosts| HTTPServer
    TCPServer -->|hosts| WebSocket
    TCPServer -->|hosts| RockRPC
    TCPServer -->|hosts| NameServer

    %% Data layer
    HTTPServer -->|serializes| ByteArray
    RockRPC -->|serializes| ByteArray
    NameServer -->|serializes| ByteArray

    ORM -->|uses| MySQLDriver
    ORM -->|uses| SQLiteDriver
    ORM -->|uses| RedisDriver
    MySQLDriver -->|pooled by| FoxThread
    SQLiteDriver -->|pooled by| FoxThread
    RedisDriver -->|pooled by| FoxThread

    MySQLDriver -->|connects to| DBService
    SQLiteDriver -->|connects to| DBService
    RedisDriver -->|connects to| DBService
    ZKClient -->|connects to| ZKService

    SMTPService

    %% Application layer
    Application -->|manages| ModuleSystem
    Application -->|runs| Daemon
    ModuleSystem -->|loads| ExampleModules
    ModuleSystem -->|loads| UserServers
    ExampleModules -->|extend| HTTPServer
    ExampleModules -->|extend| NameServer

    %% Build and config
    CMake -->|builds| bin
    Conf -->|provides| Config

    %% Click events
    click Logger "https://github.com/sylar-yin/sylar/blob/master/sylar/log.h"
    click Config "https://github.com/sylar-yin/sylar/blob/master/sylar/config.h"
    click Thread "https://github.com/sylar-yin/sylar/blob/master/sylar/thread.h"
    click Mutex "https://github.com/sylar-yin/sylar/blob/master/sylar/mutex.h"
    click Fiber "https://github.com/sylar-yin/sylar/blob/master/sylar/fiber.h"
    click Scheduler "https://github.com/sylar-yin/sylar/blob/master/sylar/scheduler.h"
    click Hook "https://github.com/sylar-yin/sylar/blob/master/sylar/hook.h"
    click IOManager "https://github.com/sylar-yin/sylar/blob/master/sylar/iomanager.h"
    click Application "https://github.com/sylar-yin/sylar/blob/master/sylar/application.h"
    click ModuleSystem "https://github.com/sylar-yin/sylar/blob/master/sylar/module.h"
    click Daemon "https://github.com/sylar-yin/sylar/blob/master/sylar/daemon.h"
    click Address "https://github.com/sylar-yin/sylar/blob/master/sylar/address.h"
    click Socket "https://github.com/sylar-yin/sylar/blob/master/sylar/socket.h"
    click Stream "https://github.com/sylar-yin/sylar/blob/master/sylar/stream.h"
    click AsyncStream "https://github.com/sylar-yin/sylar/blob/master/sylar/streams/async_socket_stream.h"
    click TCPServer "https://github.com/sylar-yin/sylar/blob/master/sylar/tcp_server.h"
    click HTTPServer "https://github.com/sylar-yin/sylar/blob/master/sylar/http/http.h"
    click WebSocket "https://github.com/sylar-yin/sylar/blob/master/sylar/http/ws_server.h"
    click RockRPC "https://github.com/sylar-yin/sylar/blob/master/sylar/rock/rock_protocol.h"
    click NameServer "https://github.com/sylar-yin/sylar/blob/master/sylar/ns/ns_protocol.h"
    click ByteArray "https://github.com/sylar-yin/sylar/blob/master/sylar/bytearray.h"
    click MySQLDriver "https://github.com/sylar-yin/sylar/blob/master/sylar/db/mysql.h"
    click SQLiteDriver "https://github.com/sylar-yin/sylar/blob/master/sylar/db/sqlite3.h"
    click RedisDriver "https://github.com/sylar-yin/sylar/blob/master/sylar/db/redis.h"
    click FoxThread "https://github.com/sylar-yin/sylar/blob/master/sylar/db/fox_thread.h"
    click ORM "https://github.com/sylar-yin/sylar/tree/master/sylar/orm"
    click ZKClient "https://github.com/sylar-yin/sylar/blob/master/sylar/zk_client.h"
    click CMake "https://github.com/sylar-yin/sylar/blob/master/CMakeLists.txt"
    click Conf "https://github.com/sylar-yin/sylar/tree/master/bin/conf"
    
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef networking fill:#90ee90,stroke:#333,stroke-width:1px
    classDef protocol fill:#ffa500,stroke:#333,stroke-width:1px
    classDef data fill:#dda0dd,stroke:#333,stroke-width:1px
    classDef app fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#f08080,stroke:#333,stroke-width:1px
    classDef build fill:#f5f5f5,stroke:#333,stroke-width:1px
```
