# theproject24/nexus_chat architecture

> Architecture diagram of the GitHub repository theproject24/nexus_chat, 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/theproject24/nexus_chat
- Repository: https://github.com/theproject24/nexus_chat

## Overview

Nexus Chat is a Go multi-room WebSocket gateway. A browser or other WebSocket client connects through the HTTP entrypoint; the client lifecycle parses join, leave, ping and room-event frames, and the hub serializes membership, history replay and pub/sub fan-out. Redis-compatible storage handles room publication and the last 50 messages; HTTP endpoints expose health and room summaries. The README also documents a browser tester. Architecture links reflect the sampled Go source and documented behavior; Titan KV is external and its implementation is not in this repository.

Main entry points: [`internal/client/hub.go`](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go) (Hub event loop), [`internal/client/client.go`](https://github.com/theproject24/nexus_chat/blob/main/internal/client/client.go) (Client lifecycle), [`cmd/server/main.go`](https://github.com/theproject24/nexus_chat/blob/main/cmd/server/main.go) (HTTP gateway), [`tester.html`](https://github.com/theproject24/nexus_chat/blob/main/tester.html) (Browser tester)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Gateway entry"]
  node_server["HTTP gateway<br/>[main.go]"]
  node_ws["WebSocket endpoint<br/>[main.go]"]
end

subgraph group_connection["WebSocket clients"]
  node_client["Client lifecycle<br/>[client.go]"]
  node_reader["Frame reader<br/>[client.go]"]
  node_writer["Frame writer<br/>[client.go]"]
end

subgraph group_routing["Room routing"]
  node_hub["Hub event loop<br/>[hub.go]"]
  node_membership["Room membership<br/>[hub.go]"]
  node_dispatch["Room dispatch<br/>[hub.go]"]
  node_replay["History replay<br/>[hub.go]"]
  node_subscriber["Room subscriber<br/>[hub.go]"]
end

subgraph group_backend["Message backend"]
  node_pubsub["Room pub/sub<br/>[hub.go]"]
  node_history[("Room history<br/>[hub.go]")]
end

subgraph group_inspection["Status inspection"]
  node_health["Health endpoint<br/>[hub.go]"]
  node_rooms["Room summary endpoint<br/>[hub.go]"]
end

node_browser(("Browser client"))
node_redis[("Redis-compatible service")]
node_tester["Browser tester<br/>[tester.html]"]

node_browser -->|"HTTP requests"| node_server
node_server -->|"pings"| node_redis
node_server -->|"starts loop"| node_hub
node_server -->|"routes /ws"| node_ws
node_browser -->|"opens WebSocket"| node_ws
node_ws -->|"creates client"| node_client
node_client -->|"starts read pump"| node_reader
node_client -->|"starts write pump"| node_writer
node_reader -->|"queues room events"| node_hub
node_hub -->|"handles membership"| node_membership
node_hub -->|"handles broadcasts"| node_dispatch
node_hub -->|"loads on join"| node_replay
node_hub -->|"starts per room"| node_subscriber
node_membership -->|"queues outbound"| node_client
node_dispatch -->|"publishes and stores"| node_redis
node_dispatch -->|"publishes room event"| node_pubsub
node_dispatch -->|"appends and trims"| node_history
node_subscriber -->|"subscribes"| node_pubsub
node_pubsub -->|"queues received event"| node_hub
node_hub -->|"fans out payload"| node_client
node_replay -->|"reads recent messages"| node_history
node_replay -->|"queues replay"| node_client
node_hub -->|"serves stats"| node_health
node_hub -->|"serves room counts"| node_rooms
node_health -->|"checks reachability"| node_redis
node_health -->|"queries counts"| node_hub
node_rooms -->|"queries membership"| node_hub
node_client -->|"sends queued frames"| node_writer
node_tester -.->|"connects manually"| node_ws

click node_server "https://github.com/theproject24/nexus_chat/blob/main/cmd/server/main.go"
click node_ws "https://github.com/theproject24/nexus_chat/blob/main/cmd/server/main.go"
click node_client "https://github.com/theproject24/nexus_chat/blob/main/internal/client/client.go"
click node_reader "https://github.com/theproject24/nexus_chat/blob/main/internal/client/client.go"
click node_writer "https://github.com/theproject24/nexus_chat/blob/main/internal/client/client.go"
click node_hub "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_membership "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_dispatch "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_replay "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_subscriber "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_pubsub "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_history "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_health "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_rooms "https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go"
click node_tester "https://github.com/theproject24/nexus_chat/blob/main/tester.html"

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_ws,node_browser,node_tester toneBlue
class node_client,node_reader,node_writer,node_redis toneAmber
class node_hub,node_membership,node_dispatch,node_replay,node_subscriber toneMint
class node_pubsub,node_history toneRose
class node_health,node_rooms toneIndigo
```

## Components

### Gateway entry

- [HTTP gateway](https://github.com/theproject24/nexus_chat/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [WebSocket endpoint](https://github.com/theproject24/nexus_chat/blob/main/cmd/server/main.go): `cmd/server/main.go`

### WebSocket clients

- [Client lifecycle](https://github.com/theproject24/nexus_chat/blob/main/internal/client/client.go): `internal/client/client.go`
- [Frame reader](https://github.com/theproject24/nexus_chat/blob/main/internal/client/client.go): `internal/client/client.go`
- [Frame writer](https://github.com/theproject24/nexus_chat/blob/main/internal/client/client.go): `internal/client/client.go`

### Room routing

- [Hub event loop](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`
- [Room membership](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`
- [Room dispatch](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`
- [History replay](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`
- [Room subscriber](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`

### Message backend

- [Room pub/sub](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`
- [Room history](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`

### Status inspection

- [Health endpoint](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`
- [Room summary endpoint](https://github.com/theproject24/nexus_chat/blob/main/internal/client/hub.go): `internal/client/hub.go`

### Other components

- **Browser client**
- **Redis-compatible service**
- [Browser tester](https://github.com/theproject24/nexus_chat/blob/main/tester.html): `tester.html`

## Connections

- Browser client → HTTP gateway: HTTP requests
- HTTP gateway → Redis-compatible service: pings
- HTTP gateway → Hub event loop: starts loop
- HTTP gateway → WebSocket endpoint: routes /ws
- Browser client → WebSocket endpoint: opens WebSocket
- WebSocket endpoint → Client lifecycle: creates client
- Client lifecycle → Frame reader: starts read pump
- Client lifecycle → Frame writer: starts write pump
- Frame reader → Hub event loop: queues room events
- Hub event loop → Room membership: handles membership
- Hub event loop → Room dispatch: handles broadcasts
- Hub event loop → History replay: loads on join
- Hub event loop → Room subscriber: starts per room
- Room membership → Client lifecycle: queues outbound
- Room dispatch → Redis-compatible service: publishes and stores
- Room dispatch → Room pub/sub: publishes room event
- Room dispatch → Room history: appends and trims
- Room subscriber → Room pub/sub: subscribes
- Room pub/sub → Hub event loop: queues received event
- Hub event loop → Client lifecycle: fans out payload
- History replay → Room history: reads recent messages
- History replay → Client lifecycle: queues replay
- Hub event loop → Health endpoint: serves stats
- Hub event loop → Room summary endpoint: serves room counts
- Health endpoint → Redis-compatible service: checks reachability
- Health endpoint → Hub event loop: queries counts
- Room summary endpoint → Hub event loop: queries membership
- Client lifecycle → Frame writer: sends queued frames
- Browser tester → WebSocket endpoint: connects manually