# nsqio/nsq architecture

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

- Interactive diagram: https://gitdiagram.com/nsqio/nsq
- Repository: https://github.com/nsqio/nsq

## Overview

NSQ is a distributed messaging platform: producers publish to nsqd, consumers receive messages, and nsqlookupd provides discovery; nsqadmin provides operational visibility and controls. The graph retains the distinct broker, lookup, administration, and client-tooling domains, plus the shared cluster-information layer. The tree and excerpts support the admin routing and broker client/auth details; most broker internals and several documented utility integrations were not sampled, so uncertain links are omitted or marked unverified.

Main entry points: [`nsqd/nsqd.go`](https://github.com/nsqio/nsq/blob/master/nsqd/nsqd.go) (Queue broker), [`nsqadmin/static/js/views/app.js`](https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/views/app.js) (Admin web app), [`nsqlookupd/nsqlookupd.go`](https://github.com/nsqio/nsq/blob/master/nsqlookupd/nsqlookupd.go) (Lookup service), [`nsqadmin/http.go`](https://github.com/nsqio/nsq/blob/master/nsqadmin/http.go) (Admin server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_broker["Message broker"]
  node_nsqd["Queue broker<br/>[nsqd.go]"]
  node_client_protocol["Client protocol<br/>[protocol_v2.go]"]
  node_client_connection["Client connection<br/>[client_v2.go]"]
  node_topic["Topic queues<br/>[topic.go]"]
  node_channel["Consumer channels<br/>[channel.go]"]
  node_message_store[("Disk queue<br/>[backend_queue.go]")]
end

subgraph group_discovery["Service discovery"]
  node_lookupd["Lookup service<br/>[nsqlookupd.go]"]
  node_registration[("Producer registry<br/>[registration_db.go]")]
  node_lookup_protocol["Lookup protocol"]
end

subgraph group_admin["Operations console"]
  node_admin_server["Admin server<br/>[http.go]"]
  node_admin_web["Admin web app<br/>[app.js]"]
  node_admin_routes["Admin routing<br/>[router.js]"]
  node_admin_state["Admin state<br/>[app_state.js]"]
  node_admin_views["Admin views<br/>[base.js]"]
end

subgraph group_clients["Client tools"]
  node_nsq_to_file["File output<br/>[nsq_to_file.go]"]
  node_nsq_to_http["HTTP output<br/>[nsq_to_http.go]"]
  node_nsq_to_nsq["NSQ relay<br/>[nsq_to_nsq.go]"]
  node_nsq_tail["Tail consumer<br/>[nsq_tail.go]"]
  node_nsq_stat["Statistics tool<br/>[nsq_stat.go]"]
  node_to_nsq["CLI publisher<br/>[to_nsq.go]"]
end

subgraph group_shared["Shared services"]
  node_cluster_info["Cluster information<br/>[data.go]"]
  node_auth["Authorization<br/>[authorizations.go]"]
end

node_producer(("Message producer"))
node_consumer(("Message consumer"))
node_nsqd_actor(("Broker operator"))
node_lookup_actor(("Service operator"))
node_admin_user(("Administrator"))
node_graphite["Graphite"]

node_producer -.->|"publishes messages"| node_nsqd
node_nsqd -.->|"serves protocol"| node_client_protocol
node_client_protocol -.->|"handles connection"| node_client_connection
node_client_connection -->|"queries authorization"| node_auth
node_nsqd -.->|"manages topics"| node_topic
node_topic -.->|"delivers messages"| node_channel
node_topic -.->|"persists messages"| node_message_store
node_channel -.->|"delivers messages"| node_consumer
node_nsqd -.->|"registers producers"| node_lookupd
node_lookupd -.->|"serves discovery"| node_lookup_protocol
node_lookupd -.->|"tracks producers"| node_registration
node_admin_user -->|"operates"| node_admin_web
node_admin_web -->|"starts routing"| node_admin_routes
node_admin_routes -->|"dispatches views"| node_admin_web
node_admin_web -->|"renders views"| node_admin_views
node_admin_web -->|"reads settings"| node_admin_state
node_admin_web -.->|"requests API"| node_admin_server
node_admin_server -->|"queries cluster"| node_cluster_info
node_cluster_info -.->|"queries producers"| node_lookupd
node_cluster_info -.->|"queries stats"| node_nsqd
node_admin_server -.->|"proxies metrics"| node_graphite
node_nsqd_actor -->|"starts broker"| node_nsqd
node_lookup_actor -->|"starts service"| node_lookupd
node_admin_user -.->|"administers cluster"| node_admin_server
node_nsq_to_file -.->|"consumes messages"| node_nsqd
node_nsq_to_http -.->|"consumes messages"| node_nsqd
node_nsq_to_nsq -.->|"relays messages"| node_nsqd
node_nsq_tail -.->|"consumes messages"| node_nsqd
node_nsq_stat -->|"collects stats"| node_cluster_info
node_to_nsq -.->|"publishes messages"| node_nsqd

click node_nsqd "https://github.com/nsqio/nsq/blob/master/nsqd/nsqd.go"
click node_client_protocol "https://github.com/nsqio/nsq/blob/master/nsqd/protocol_v2.go"
click node_client_connection "https://github.com/nsqio/nsq/blob/master/nsqd/client_v2.go"
click node_topic "https://github.com/nsqio/nsq/blob/master/nsqd/topic.go"
click node_channel "https://github.com/nsqio/nsq/blob/master/nsqd/channel.go"
click node_message_store "https://github.com/nsqio/nsq/blob/master/nsqd/backend_queue.go"
click node_lookupd "https://github.com/nsqio/nsq/blob/master/nsqlookupd/nsqlookupd.go"
click node_registration "https://github.com/nsqio/nsq/blob/master/nsqlookupd/registration_db.go"
click node_lookup_protocol "https://github.com/nsqio/nsq/blob/master/nsqlookupd/lookup_protocol_v1.go"
click node_admin_server "https://github.com/nsqio/nsq/blob/master/nsqadmin/http.go"
click node_admin_web "https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/views/app.js"
click node_admin_routes "https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/router.js"
click node_admin_state "https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/app_state.js"
click node_admin_views "https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/views/base.js"
click node_cluster_info "https://github.com/nsqio/nsq/blob/master/internal/clusterinfo/data.go"
click node_nsq_to_file "https://github.com/nsqio/nsq/blob/master/apps/nsq_to_file/nsq_to_file.go"
click node_nsq_to_http "https://github.com/nsqio/nsq/blob/master/apps/nsq_to_http/nsq_to_http.go"
click node_nsq_to_nsq "https://github.com/nsqio/nsq/blob/master/apps/nsq_to_nsq/nsq_to_nsq.go"
click node_nsq_tail "https://github.com/nsqio/nsq/blob/master/apps/nsq_tail/nsq_tail.go"
click node_nsq_stat "https://github.com/nsqio/nsq/blob/master/apps/nsq_stat/nsq_stat.go"
click node_to_nsq "https://github.com/nsqio/nsq/blob/master/apps/to_nsq/to_nsq.go"
click node_auth "https://github.com/nsqio/nsq/blob/master/internal/auth/authorizations.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_nsqd,node_client_protocol,node_client_connection,node_topic,node_channel,node_message_store toneBlue
class node_lookupd,node_registration,node_lookup_protocol toneAmber
class node_admin_server,node_admin_web,node_admin_routes,node_admin_state,node_admin_views toneMint
class node_nsq_to_file,node_nsq_to_http,node_nsq_to_nsq,node_nsq_tail,node_nsq_stat,node_to_nsq toneRose
class node_cluster_info,node_auth,node_producer,node_consumer,node_nsqd_actor,node_lookup_actor,node_admin_user,node_graphite toneIndigo
```

## Components

### Message broker

- [Queue broker](https://github.com/nsqio/nsq/blob/master/nsqd/nsqd.go): `nsqd/nsqd.go`
- [Client protocol](https://github.com/nsqio/nsq/blob/master/nsqd/protocol_v2.go): `nsqd/protocol_v2.go`
- [Client connection](https://github.com/nsqio/nsq/blob/master/nsqd/client_v2.go): `nsqd/client_v2.go`
- [Topic queues](https://github.com/nsqio/nsq/blob/master/nsqd/topic.go): `nsqd/topic.go`
- [Consumer channels](https://github.com/nsqio/nsq/blob/master/nsqd/channel.go): `nsqd/channel.go`
- [Disk queue](https://github.com/nsqio/nsq/blob/master/nsqd/backend_queue.go): `nsqd/backend_queue.go`

### Service discovery

- [Lookup service](https://github.com/nsqio/nsq/blob/master/nsqlookupd/nsqlookupd.go): `nsqlookupd/nsqlookupd.go`
- [Producer registry](https://github.com/nsqio/nsq/blob/master/nsqlookupd/registration_db.go): `nsqlookupd/registration_db.go`
- [Lookup protocol](https://github.com/nsqio/nsq/blob/master/nsqlookupd/lookup_protocol_v1.go): `nsqlookupd/lookup_protocol_v1.go`

### Operations console

- [Admin server](https://github.com/nsqio/nsq/blob/master/nsqadmin/http.go): `nsqadmin/http.go`
- [Admin web app](https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/views/app.js): `nsqadmin/static/js/views/app.js`
- [Admin routing](https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/router.js): `nsqadmin/static/js/router.js`
- [Admin state](https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/app_state.js): `nsqadmin/static/js/app_state.js`
- [Admin views](https://github.com/nsqio/nsq/blob/master/nsqadmin/static/js/views/base.js): `nsqadmin/static/js/views/base.js`

### Client tools

- [File output](https://github.com/nsqio/nsq/blob/master/apps/nsq_to_file/nsq_to_file.go): `apps/nsq_to_file/nsq_to_file.go`
- [HTTP output](https://github.com/nsqio/nsq/blob/master/apps/nsq_to_http/nsq_to_http.go): `apps/nsq_to_http/nsq_to_http.go`
- [NSQ relay](https://github.com/nsqio/nsq/blob/master/apps/nsq_to_nsq/nsq_to_nsq.go): `apps/nsq_to_nsq/nsq_to_nsq.go`
- [Tail consumer](https://github.com/nsqio/nsq/blob/master/apps/nsq_tail/nsq_tail.go): `apps/nsq_tail/nsq_tail.go`
- [Statistics tool](https://github.com/nsqio/nsq/blob/master/apps/nsq_stat/nsq_stat.go): `apps/nsq_stat/nsq_stat.go`
- [CLI publisher](https://github.com/nsqio/nsq/blob/master/apps/to_nsq/to_nsq.go): `apps/to_nsq/to_nsq.go`

### Shared services

- [Cluster information](https://github.com/nsqio/nsq/blob/master/internal/clusterinfo/data.go): `internal/clusterinfo/data.go`
- [Authorization](https://github.com/nsqio/nsq/blob/master/internal/auth/authorizations.go): `internal/auth/authorizations.go`

### Other components

- **Message producer**
- **Message consumer**
- **Broker operator**
- **Service operator**
- **Administrator**
- **Graphite**

## Connections

- Message producer → Queue broker: publishes messages
- Queue broker → Client protocol: serves protocol
- Client protocol → Client connection: handles connection
- Client connection → Authorization: queries authorization (evidence: `nsqd/client_v2.go`)
- Queue broker → Topic queues: manages topics
- Topic queues → Consumer channels: delivers messages
- Topic queues → Disk queue: persists messages
- Consumer channels → Message consumer: delivers messages
- Queue broker → Lookup service: registers producers
- Lookup service → Lookup protocol: serves discovery
- Lookup service → Producer registry: tracks producers
- Administrator → Admin web app: operates
- Admin web app → Admin routing: starts routing (evidence: `nsqadmin/static/js/main.js`)
- Admin routing → Admin web app: dispatches views (evidence: `nsqadmin/static/js/router.js`)
- Admin web app → Admin views: renders views (evidence: `nsqadmin/static/js/views/app.js`)
- Admin web app → Admin state: reads settings (evidence: `nsqadmin/static/js/views/app.js`)
- Admin web app → Admin server: requests API
- Admin server → Cluster information: queries cluster (evidence: `nsqadmin/http.go`)
- Cluster information → Lookup service: queries producers
- Cluster information → Queue broker: queries stats
- Admin server → Graphite: proxies metrics (evidence: `nsqadmin/http.go`)
- Broker operator → Queue broker: starts broker
- Service operator → Lookup service: starts service
- Administrator → Admin server: administers cluster
- File output → Queue broker: consumes messages
- HTTP output → Queue broker: consumes messages
- NSQ relay → Queue broker: relays messages
- Tail consumer → Queue broker: consumes messages
- Statistics tool → Cluster information: collects stats (evidence: `apps/nsq_stat/nsq_stat.go`)
- CLI publisher → Queue broker: publishes messages
