# evobytes/nats-ws-gateway-and-server architecture

> Architecture diagram of the GitHub repository evobytes/nats-ws-gateway-and-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evobytes/nats-ws-gateway-and-server
- Repository: https://github.com/evobytes/nats-ws-gateway-and-server
- Video tour (about a minute): https://gitdiagram.com/evobytes/nats-ws-gateway-and-server/video

## Overview

This repository packages an embedded NATS server with a WebSocket/HTTP gateway. Clients send messages on a topic through WebSockets or HTTP POST; the gateway publishes them to NATS, whose subscriptions deliver messages back to WebSocket clients. A QUERY /status endpoint reports uptime and observed topics. Separate utilities provide traffic logging and basic NATS pub/sub, with sample clients in several languages. The main server excerpt is partial, so some handler wiring and topic-stat recording details are not shown.

Main entry points: [`cmd/nats-ws-gateway-and-server/main.go`](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go) (Embedded NATS), [`cmd/nats-ws-gateway-and-server/nats-cli/pub.go`](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/pub.go) (CLI publisher), [`cmd/nats-ws-gateway-and-server/nats-cli/sub.go`](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/sub.go) (CLI subscriber), [`cmd/nats-ws-gateway-and-server-logger/main.go`](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server-logger/main.go) (Traffic logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway"]
  node_gateway_server["Gateway server<br/>[main.go]"]
  node_websocket_bridge["WebSocket bridge<br/>[main.go]"]
  node_http_publish["HTTP publish<br/>[main.go]"]
  node_status_api["Status API<br/>[main.go]"]
  node_topic_stats["Topic statistics<br/>[main.go]"]
  node_embedded_nats["Embedded NATS<br/>[main.go]"]
end

subgraph group_ops["Operations"]
  node_traffic_logger["Traffic logger<br/>[main.go]"]
  node_traffic_log["Traffic log"]
end

subgraph group_clients["Client tools"]
  node_cli_dispatch["CLI dispatcher<br/>[main.go]"]
  node_cli_config["CLI connection config<br/>[config.go]"]
  node_cli_publish["CLI publisher<br/>[pub.go]"]
  node_cli_subscribe["CLI subscriber<br/>[sub.go]"]
  node_example_clients["Example clients"]
end

node_websocket_users(("WebSocket users"))
node_http_users(("HTTP callers"))
node_native_nats_users(("NATS clients"))

node_websocket_users -->|"connects to"| node_websocket_bridge
node_http_users -->|"posts messages"| node_http_publish
node_http_users -->|"queries status"| node_status_api
node_gateway_server -->|"starts and connects"| node_embedded_nats
node_websocket_bridge -->|"publishes messages"| node_embedded_nats
node_embedded_nats -->|"delivers messages"| node_websocket_bridge
node_http_publish -->|"publishes messages"| node_embedded_nats
node_status_api -->|"reads snapshot"| node_topic_stats
node_native_nats_users -->|"connects to"| node_embedded_nats
node_traffic_logger -->|"subscribes to all"| node_embedded_nats
node_traffic_logger -->|"writes records"| node_traffic_log
node_cli_dispatch -->|"dispatches publish"| node_cli_publish
node_cli_dispatch -->|"dispatches subscribe"| node_cli_subscribe
node_cli_publish -->|"resolves URL"| node_cli_config
node_cli_subscribe -->|"resolves URL"| node_cli_config
node_cli_publish -->|"publishes messages"| node_embedded_nats
node_cli_subscribe -->|"subscribes to subject"| node_embedded_nats
node_example_clients -->|"connect over WebSocket"| node_websocket_bridge

click node_gateway_server "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go"
click node_websocket_bridge "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go"
click node_http_publish "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go"
click node_status_api "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go"
click node_topic_stats "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go"
click node_embedded_nats "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go"
click node_traffic_logger "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server-logger/main.go"
click node_cli_dispatch "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/main.go"
click node_cli_config "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/config.go"
click node_cli_publish "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/pub.go"
click node_cli_subscribe "https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/sub.go"
click node_example_clients "https://github.com/evobytes/nats-ws-gateway-and-server/tree/main/client-examples"

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_gateway_server,node_websocket_bridge,node_http_publish,node_status_api,node_topic_stats,node_embedded_nats,node_websocket_users,node_native_nats_users toneBlue
class node_traffic_logger,node_traffic_log toneAmber
class node_cli_dispatch,node_cli_config,node_cli_publish,node_cli_subscribe,node_example_clients toneMint
class node_http_users toneIndigo
```

## Components

### Gateway

- [Gateway server](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go): `cmd/nats-ws-gateway-and-server/main.go`
- [WebSocket bridge](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go): `cmd/nats-ws-gateway-and-server/main.go`
- [HTTP publish](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go): `cmd/nats-ws-gateway-and-server/main.go`
- [Status API](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go): `cmd/nats-ws-gateway-and-server/main.go`
- [Topic statistics](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go): `cmd/nats-ws-gateway-and-server/main.go`
- [Embedded NATS](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/main.go): `cmd/nats-ws-gateway-and-server/main.go`

### Operations

- [Traffic logger](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server-logger/main.go): `cmd/nats-ws-gateway-and-server-logger/main.go`
- **Traffic log**

### Client tools

- [CLI dispatcher](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/main.go): `cmd/nats-ws-gateway-and-server/nats-cli/main.go`
- [CLI connection config](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/config.go): `cmd/nats-ws-gateway-and-server/nats-cli/config.go`
- [CLI publisher](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/pub.go): `cmd/nats-ws-gateway-and-server/nats-cli/pub.go`
- [CLI subscriber](https://github.com/evobytes/nats-ws-gateway-and-server/blob/main/cmd/nats-ws-gateway-and-server/nats-cli/sub.go): `cmd/nats-ws-gateway-and-server/nats-cli/sub.go`
- [Example clients](https://github.com/evobytes/nats-ws-gateway-and-server/tree/main/client-examples): `client-examples`

### Other components

- **WebSocket users**
- **HTTP callers**
- **NATS clients**

## Connections

- WebSocket users → WebSocket bridge: connects to (evidence: `README.md`)
- HTTP callers → HTTP publish: posts messages (evidence: `cmd/nats-ws-gateway-and-server/main.go`)
- HTTP callers → Status API: queries status (evidence: `README.md`)
- Gateway server → Embedded NATS: starts and connects (evidence: `cmd/nats-ws-gateway-and-server/main.go`)
- WebSocket bridge → Embedded NATS: publishes messages (evidence: `cmd/nats-ws-gateway-and-server/main.go`)
- Embedded NATS → WebSocket bridge: delivers messages (evidence: `cmd/nats-ws-gateway-and-server/main.go`)
- HTTP publish → Embedded NATS: publishes messages (evidence: `cmd/nats-ws-gateway-and-server/main.go`)
- Status API → Topic statistics: reads snapshot (evidence: `cmd/nats-ws-gateway-and-server/main.go`)
- NATS clients → Embedded NATS: connects to (evidence: `README.md`)
- Traffic logger → Embedded NATS: subscribes to all (evidence: `cmd/nats-ws-gateway-and-server-logger/main.go`)
- Traffic logger → Traffic log: writes records (evidence: `cmd/nats-ws-gateway-and-server-logger/main.go`)
- CLI dispatcher → CLI publisher: dispatches publish (evidence: `cmd/nats-ws-gateway-and-server/nats-cli/main.go`)
- CLI dispatcher → CLI subscriber: dispatches subscribe (evidence: `cmd/nats-ws-gateway-and-server/nats-cli/main.go`)
- CLI publisher → CLI connection config: resolves URL (evidence: `cmd/nats-ws-gateway-and-server/nats-cli/pub.go`)
- CLI subscriber → CLI connection config: resolves URL (evidence: `cmd/nats-ws-gateway-and-server/nats-cli/sub.go`)
- CLI publisher → Embedded NATS: publishes messages (evidence: `cmd/nats-ws-gateway-and-server/nats-cli/pub.go`)
- CLI subscriber → Embedded NATS: subscribes to subject (evidence: `cmd/nats-ws-gateway-and-server/nats-cli/sub.go`)
- Example clients → WebSocket bridge: connect over WebSocket (evidence: `README.md`)
