# allenxuxu/gev architecture

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

- Interactive diagram: https://gitdiagram.com/allenxuxu/gev
- Repository: https://github.com/allenxuxu/gev

## Overview

gev is a Go TCP reactor library for building custom-protocol and WebSocket servers. A client connects through the listener; the server assigns its connection to a worker event loop, which dispatches socket events. The connection buffers and unpacks frames, invokes the application handler, packs any response, and schedules writes on the loop. The README also documents multi-loop load balancing, async sends, idle cleanup, and scheduled tasks. Plugin internals are represented from documented capabilities and the sampled plugin files; unsampled connection and listener wiring is shown only where documented.

Main entry points: [`server.go`](https://github.com/allenxuxu/gev/blob/master/server.go) (Server), [`connection.go`](https://github.com/allenxuxu/gev/blob/master/connection.go) (Connection), [`eventloop/eventloop.go`](https://github.com/allenxuxu/gev/blob/master/eventloop/eventloop.go) (Event loop), [`protocol.go`](https://github.com/allenxuxu/gev/blob/master/protocol.go) (Protocol interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Server lifecycle"]
  node_server["Server<br/>[server.go]"]
  node_listener["Listener<br/>[listener.go]"]
  node_loadbalance["Loop strategy<br/>[load_balance.go]"]
end

subgraph group_io["Reactor I/O"]
  node_loop["Event loop<br/>[eventloop.go]"]
  node_poller["OS poller<br/>[poller.go]"]
  node_connection["Connection<br/>[connection.go]"]
  node_ringbuffer["Ring buffer"]
end

subgraph group_protocols["Protocol support"]
  node_protocol["Protocol interface<br/>[protocol.go]"]
  node_protobuf["Protobuf plugin<br/>[protocol.go]"]
  node_websocket["WebSocket protocol<br/>[protocol.go]"]
  node_wswrap["WebSocket handler wrap<br/>[wrap.go]"]
  node_wswire["WebSocket framing<br/>[ws.go]"]
end

subgraph group_timing["Timers and options"]
  node_timingwheel["Timing wheel"]
  node_scheduler["Scheduled tasks<br/>[everyscheduler.go]"]
  node_options["Server options<br/>[options.go]"]
end

node_client(("TCP client"))
node_handler["Application handler"]

node_client -->|"connects"| node_listener
node_server -->|"starts"| node_listener
node_listener -->|"accepted fd"| node_server
node_server -->|"selects loop"| node_loadbalance
node_server -->|"runs workers"| node_loop
node_server -->|"creates"| node_connection
node_server -->|"connect callback"| node_handler
node_loop -->|"polls events"| node_poller
node_poller -->|"dispatches events"| node_loop
node_loop -->|"dispatches socket events"| node_connection
node_connection -->|"buffers bytes"| node_ringbuffer
node_connection -->|"unpacks frames"| node_protocol
node_connection -->|"delivers messages"| node_handler
node_handler -->|"returns response"| node_connection
node_connection -->|"packs responses"| node_protocol
node_connection -->|"queues async writes"| node_loop
node_server -->|"configures"| node_options
node_server -->|"starts timers"| node_timingwheel
node_server -->|"schedules recurring tasks"| node_scheduler
node_scheduler -->|"uses"| node_timingwheel
node_protobuf -->|"implements"| node_protocol
node_websocket -->|"implements"| node_protocol
node_websocket -->|"parses and frames"| node_wswire
node_wswrap -->|"delegates messages"| node_handler

click node_server "https://github.com/allenxuxu/gev/blob/master/server.go"
click node_listener "https://github.com/allenxuxu/gev/blob/master/listener.go"
click node_loadbalance "https://github.com/allenxuxu/gev/blob/master/load_balance.go"
click node_loop "https://github.com/allenxuxu/gev/blob/master/eventloop/eventloop.go"
click node_poller "https://github.com/allenxuxu/gev/blob/master/poller/poller.go"
click node_connection "https://github.com/allenxuxu/gev/blob/master/connection.go"
click node_protocol "https://github.com/allenxuxu/gev/blob/master/protocol.go"
click node_protobuf "https://github.com/allenxuxu/gev/blob/master/plugins/protobuf/protocol.go"
click node_websocket "https://github.com/allenxuxu/gev/blob/master/plugins/websocket/protocol.go"
click node_wswrap "https://github.com/allenxuxu/gev/blob/master/plugins/websocket/wrap.go"
click node_wswire "https://github.com/allenxuxu/gev/blob/master/plugins/websocket/ws/ws.go"
click node_scheduler "https://github.com/allenxuxu/gev/blob/master/everyscheduler.go"
click node_options "https://github.com/allenxuxu/gev/blob/master/options.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_listener,node_loadbalance,node_client toneBlue
class node_loop,node_poller,node_connection,node_ringbuffer toneAmber
class node_protocol,node_protobuf,node_websocket,node_wswrap,node_wswire,node_handler toneMint
class node_timingwheel,node_scheduler,node_options toneRose
```

## Components

### Server lifecycle

- [Server](https://github.com/allenxuxu/gev/blob/master/server.go): `server.go`
- [Listener](https://github.com/allenxuxu/gev/blob/master/listener.go): `listener.go`
- [Loop strategy](https://github.com/allenxuxu/gev/blob/master/load_balance.go): `load_balance.go`

### Reactor I/O

- [Event loop](https://github.com/allenxuxu/gev/blob/master/eventloop/eventloop.go): `eventloop/eventloop.go`
- [OS poller](https://github.com/allenxuxu/gev/blob/master/poller/poller.go): `poller/poller.go`
- [Connection](https://github.com/allenxuxu/gev/blob/master/connection.go): `connection.go`
- **Ring buffer**

### Protocol support

- [Protocol interface](https://github.com/allenxuxu/gev/blob/master/protocol.go): `protocol.go`
- [Protobuf plugin](https://github.com/allenxuxu/gev/blob/master/plugins/protobuf/protocol.go): `plugins/protobuf/protocol.go`
- [WebSocket protocol](https://github.com/allenxuxu/gev/blob/master/plugins/websocket/protocol.go): `plugins/websocket/protocol.go`
- [WebSocket handler wrap](https://github.com/allenxuxu/gev/blob/master/plugins/websocket/wrap.go): `plugins/websocket/wrap.go`
- [WebSocket framing](https://github.com/allenxuxu/gev/blob/master/plugins/websocket/ws/ws.go): `plugins/websocket/ws/ws.go`

### Timers and options

- **Timing wheel**
- [Scheduled tasks](https://github.com/allenxuxu/gev/blob/master/everyscheduler.go): `everyscheduler.go`
- [Server options](https://github.com/allenxuxu/gev/blob/master/options.go): `options.go`

### Other components

- **TCP client**
- **Application handler**

## Connections

- TCP client → Listener: connects
- Server → Listener: starts
- Listener → Server: accepted fd
- Server → Loop strategy: selects loop
- Server → Event loop: runs workers
- Server → Connection: creates
- Server → Application handler: connect callback
- Event loop → OS poller: polls events
- OS poller → Event loop: dispatches events
- Event loop → Connection: dispatches socket events
- Connection → Ring buffer: buffers bytes
- Connection → Protocol interface: unpacks frames
- Connection → Application handler: delivers messages
- Application handler → Connection: returns response
- Connection → Protocol interface: packs responses
- Connection → Event loop: queues async writes
- Server → Server options: configures
- Server → Timing wheel: starts timers
- Server → Scheduled tasks: schedules recurring tasks
- Scheduled tasks → Timing wheel: uses
- Protobuf plugin → Protocol interface: implements
- WebSocket protocol → Protocol interface: implements
- WebSocket protocol → WebSocket framing: parses and frames
- WebSocket handler wrap → Application handler: delegates messages