# catalinfl/adler architecture

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

- Interactive diagram: https://gitdiagram.com/catalinfl/adler
- Repository: https://github.com/catalinfl/adler

## Overview

Adler is a Go WebSocket server toolkit. An application routes HTTP requests to Adler, which upgrades each connection, registers a session, and dispatches lifecycle and message callbacks; applications then send messages directly, globally, or through rooms. Its optional matchmaker accepts session queue requests, promotes waiting clients, creates rooms, and notifies participants. The graph reflects documented capabilities as well as sampled runtime paths; some internal callback and matchmaker details are documented but not fully sampled.

Main entry points: [`session.go`](https://github.com/catalinfl/adler/blob/master/session.go) (Session), [`adler.go`](https://github.com/catalinfl/adler/blob/master/adler.go) (Adler Server), [`matchmaker/matchmaking.go`](https://github.com/catalinfl/adler/blob/master/matchmaker/matchmaking.go) (Matchmaker Worker), [`room.go`](https://github.com/catalinfl/adler/blob/master/room.go) (Room Membership)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server Lifecycle"]
  node_adler["Adler Server<br/>[adler.go]"]
  node_config["Runtime Config<br/>[config.go]"]
  node_gws["gws Engine"]
  node_core["Session Registry<br/>[core.go]"]
  node_session["Session<br/>[session.go]"]
  node_callbacks["Lifecycle Handlers<br/>[adler.go]"]
end

subgraph group_messaging["Messaging"]
  node_serializer["Protocol Serializer<br/>[serializer.go]"]
  node_broadcast["Global Broadcast<br/>[adler.go]"]
  node_outbound["Outbound Queue<br/>[message.go]"]
end

subgraph group_rooms["Rooms"]
  node_room["Room Membership<br/>[room.go]"]
  node_room_broadcast["Room Broadcast<br/>[room.go]"]
end

subgraph group_matching["Matchmaking"]
  node_matchmaker["Matchmaker Worker<br/>[matchmaking.go]"]
  node_queues["Match Queues<br/>[matchmaking.go]"]
  node_queue_events["Queue Events<br/>[matchmaking.proto]"]
end

node_http_app(("HTTP Application"))
node_client(("WebSocket Client"))

node_http_app -->|"handles request"| node_adler
node_adler -->|"upgrades connection"| node_gws
node_gws -->|"provides connection"| node_session
node_adler -->|"registers session"| node_core
node_adler -->|"dispatches hooks"| node_callbacks
node_session -->|"dispatches frames"| node_callbacks
node_client -->|"sends frames"| node_gws
node_session -->|"reads frames"| node_gws
node_session -->|"encodes protocol messages"| node_serializer
node_session -->|"queues writes"| node_outbound
node_outbound -->|"writes frames"| node_gws
node_adler -->|"offers send helpers"| node_broadcast
node_broadcast -->|"selects sessions"| node_core
node_core -->|"dispatches writes"| node_session
node_adler -->|"creates rooms"| node_room
node_room -->|"tracks members"| node_session
node_room_broadcast -->|"dispatches writes"| node_session
node_room -->|"broadcasts to members"| node_room_broadcast
node_matchmaker -->|"manages queues"| node_queues
node_matchmaker -->|"creates and joins rooms"| node_room
node_matchmaker -->|"updates status and sends events"| node_session
node_matchmaker -->|"emits event types"| node_queue_events
node_matchmaker -->|"uses server protocol"| node_adler

click node_adler "https://github.com/catalinfl/adler/blob/master/adler.go"
click node_config "https://github.com/catalinfl/adler/blob/master/config.go"
click node_core "https://github.com/catalinfl/adler/blob/master/core.go"
click node_session "https://github.com/catalinfl/adler/blob/master/session.go"
click node_callbacks "https://github.com/catalinfl/adler/blob/master/adler.go"
click node_serializer "https://github.com/catalinfl/adler/blob/master/serializer.go"
click node_broadcast "https://github.com/catalinfl/adler/blob/master/adler.go"
click node_outbound "https://github.com/catalinfl/adler/blob/master/message.go"
click node_room "https://github.com/catalinfl/adler/blob/master/room.go"
click node_room_broadcast "https://github.com/catalinfl/adler/blob/master/room.go"
click node_matchmaker "https://github.com/catalinfl/adler/blob/master/matchmaker/matchmaking.go"
click node_queues "https://github.com/catalinfl/adler/blob/master/matchmaker/matchmaking.go"
click node_queue_events "https://github.com/catalinfl/adler/blob/master/matchmaker/matchmaking.proto"

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_adler,node_config,node_gws,node_core,node_session,node_callbacks,node_client toneBlue
class node_serializer,node_broadcast,node_outbound toneAmber
class node_room,node_room_broadcast toneMint
class node_matchmaker,node_queues,node_queue_events toneRose
class node_http_app toneIndigo
```

## Components

### Server Lifecycle

- [Adler Server](https://github.com/catalinfl/adler/blob/master/adler.go): `adler.go`
- [Runtime Config](https://github.com/catalinfl/adler/blob/master/config.go): `config.go`
- **gws Engine**
- [Session Registry](https://github.com/catalinfl/adler/blob/master/core.go): `core.go`
- [Session](https://github.com/catalinfl/adler/blob/master/session.go): `session.go`
- [Lifecycle Handlers](https://github.com/catalinfl/adler/blob/master/adler.go): `adler.go`

### Messaging

- [Protocol Serializer](https://github.com/catalinfl/adler/blob/master/serializer.go): `serializer.go`
- [Global Broadcast](https://github.com/catalinfl/adler/blob/master/adler.go): `adler.go`
- [Outbound Queue](https://github.com/catalinfl/adler/blob/master/message.go): `message.go`

### Rooms

- [Room Membership](https://github.com/catalinfl/adler/blob/master/room.go): `room.go`
- [Room Broadcast](https://github.com/catalinfl/adler/blob/master/room.go): `room.go`

### Matchmaking

- [Matchmaker Worker](https://github.com/catalinfl/adler/blob/master/matchmaker/matchmaking.go): `matchmaker/matchmaking.go`
- [Match Queues](https://github.com/catalinfl/adler/blob/master/matchmaker/matchmaking.go): `matchmaker/matchmaking.go`
- [Queue Events](https://github.com/catalinfl/adler/blob/master/matchmaker/matchmaking.proto): `matchmaker/matchmaking.proto`

### Other components

- **HTTP Application**
- **WebSocket Client**

## Connections

- HTTP Application → Adler Server: handles request
- Adler Server → gws Engine: upgrades connection
- gws Engine → Session: provides connection
- Adler Server → Session Registry: registers session
- Adler Server → Lifecycle Handlers: dispatches hooks
- Session → Lifecycle Handlers: dispatches frames
- WebSocket Client → gws Engine: sends frames
- Session → gws Engine: reads frames
- Session → Protocol Serializer: encodes protocol messages
- Session → Outbound Queue: queues writes
- Outbound Queue → gws Engine: writes frames
- Adler Server → Global Broadcast: offers send helpers
- Global Broadcast → Session Registry: selects sessions
- Session Registry → Session: dispatches writes
- Adler Server → Room Membership: creates rooms
- Room Membership → Session: tracks members
- Room Broadcast → Session: dispatches writes
- Room Membership → Room Broadcast: broadcasts to members
- Matchmaker Worker → Match Queues: manages queues
- Matchmaker Worker → Room Membership: creates and joins rooms
- Matchmaker Worker → Session: updates status and sends events
- Matchmaker Worker → Queue Events: emits event types
- Matchmaker Worker → Adler Server: uses server protocol