# pablitovicente/mqtt-to-nats architecture

> Architecture diagram of the GitHub repository pablitovicente/mqtt-to-nats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pablitovicente/mqtt-to-nats
- Repository: https://github.com/pablitovicente/mqtt-to-nats

## Overview

MQTT to NATS is a Go bridge that subscribes to MQTT topic filters and stores received messages in NATS JetStream. Users provide one route through flags or several through a YAML file; the CLI loads and validates settings, then the bridge prepares streams and starts one independent MQTT client, queue, and publisher per route. Publishers convert topics to NATS subjects, retry unconfirmed writes, and drain queued messages during shutdown. The README documents reconnect handling, TLS, stream sharing, message IDs, and operational counters; unsampled implementations are represented only where their paths are supported. Arrows are limited to relationships visible in excerpts or explicitly documented.

Main entry points: [`internal/bridge/publisher.go`](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/publisher.go) (Publish and retry), [`internal/broker/paho.go`](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/broker/paho.go) (MQTT client), [`internal/cli/root.go`](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/cli/root.go) (CLI command), [`internal/bridge/bridge.go`](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/bridge.go) (Bridge orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_cli["CLI command<br/>[root.go]"]
  node_route_file["Routes YAML<br/>[routes_file.go]"]
  node_settings["Settings validation<br/>[config.go]"]
  node_entry["Process entry<br/>[main.go]"]
end

subgraph group_bridge["Bridge runtime"]
  node_bridge_run["Bridge orchestration<br/>[bridge.go]"]
  node_streams["Stream setup<br/>[streams.go]"]
  node_route_runtime["Route lifecycle<br/>[route.go]"]
  node_queue["Message queue<br/>[queue.go]"]
  node_publisher["Publish and retry<br/>[publisher.go]"]
  node_stats["Route statistics<br/>[stats.go]"]
end

subgraph group_protocols["Protocol clients"]
  node_mqtt_client["MQTT client<br/>[paho.go]"]
  node_mqtt_api["Broker interface<br/>[broker.go]"]
  node_tls["MQTT TLS<br/>[tls.go]"]
end

subgraph group_topics["Topic mapping"]
  node_filter_rules["Filter rules<br/>[filter.go]"]
  node_subject_mapping["Subject conversion<br/>[subject.go]"]
end

node_operator(("Operator"))
node_mqtt_broker(("MQTT broker"))
node_nats[("NATS JetStream")]

node_operator -->|"starts"| node_entry
node_entry -->|"executes"| node_cli
node_operator -.->|"supplies routes"| node_route_file
node_cli -->|"loads"| node_route_file
node_cli -->|"validates"| node_settings
node_cli -->|"runs"| node_bridge_run
node_settings -->|"checks routes"| node_filter_rules
node_settings -->|"checks subjects"| node_subject_mapping
node_bridge_run -->|"sets up streams"| node_streams
node_bridge_run -->|"starts routes"| node_route_runtime
node_bridge_run -->|"reports counters"| node_stats
node_route_runtime -->|"connects"| node_mqtt_client
node_route_runtime -->|"creates"| node_queue
node_route_runtime -->|"starts"| node_publisher
node_mqtt_client -->|"implements"| node_mqtt_api
node_mqtt_client -.->|"configures TLS"| node_tls
node_mqtt_client -->|"subscribes"| node_mqtt_broker
node_mqtt_broker -.->|"delivers messages"| node_mqtt_client
node_publisher -->|"drains messages"| node_queue
node_publisher -->|"converts topics"| node_subject_mapping
node_publisher -->|"publishes"| node_nats
node_streams -.->|"creates streams"| node_nats
node_stats -.->|"reads counters"| node_publisher

click node_cli "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/cli/root.go"
click node_route_file "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/cli/routes_file.go"
click node_settings "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/cli/config.go"
click node_entry "https://github.com/pablitovicente/mqtt-to-nats/blob/main/cmd/main.go"
click node_bridge_run "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/bridge.go"
click node_streams "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/streams.go"
click node_route_runtime "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/route.go"
click node_queue "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/queue.go"
click node_publisher "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/publisher.go"
click node_stats "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/stats.go"
click node_mqtt_client "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/broker/paho.go"
click node_mqtt_api "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/broker/broker.go"
click node_tls "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/broker/tls.go"
click node_filter_rules "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/topics/filter.go"
click node_subject_mapping "https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/topics/subject.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_cli,node_route_file,node_settings,node_entry toneBlue
class node_bridge_run,node_streams,node_route_runtime,node_queue,node_publisher,node_stats,node_nats toneAmber
class node_mqtt_client,node_mqtt_api,node_tls toneMint
class node_filter_rules,node_subject_mapping toneRose
class node_operator,node_mqtt_broker toneIndigo
```

## Components

### Configuration

- [CLI command](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/cli/root.go): `internal/cli/root.go`
- [Routes YAML](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/cli/routes_file.go): `internal/cli/routes_file.go`
- [Settings validation](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/cli/config.go): `internal/cli/config.go`
- [Process entry](https://github.com/pablitovicente/mqtt-to-nats/blob/main/cmd/main.go): `cmd/main.go`

### Bridge runtime

- [Bridge orchestration](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/bridge.go): `internal/bridge/bridge.go`
- [Stream setup](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/streams.go): `internal/bridge/streams.go`
- [Route lifecycle](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/route.go): `internal/bridge/route.go`
- [Message queue](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/queue.go): `internal/bridge/queue.go`
- [Publish and retry](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/publisher.go): `internal/bridge/publisher.go`
- [Route statistics](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/bridge/stats.go): `internal/bridge/stats.go`

### Protocol clients

- [MQTT client](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/broker/paho.go): `internal/broker/paho.go`
- [Broker interface](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/broker/broker.go): `internal/broker/broker.go`
- [MQTT TLS](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/broker/tls.go): `internal/broker/tls.go`

### Topic mapping

- [Filter rules](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/topics/filter.go): `internal/topics/filter.go`
- [Subject conversion](https://github.com/pablitovicente/mqtt-to-nats/blob/main/internal/topics/subject.go): `internal/topics/subject.go`

### Other components

- **Operator**
- **MQTT broker**
- **NATS JetStream**

## Connections

- Operator → Process entry: starts (evidence: `cmd/main.go`)
- Process entry → CLI command: executes (evidence: `cmd/main.go`)
- Operator → Routes YAML: supplies routes (evidence: `README.md`)
- CLI command → Routes YAML: loads (evidence: `internal/cli/routes_file.go`)
- CLI command → Settings validation: validates (evidence: `internal/cli/config.go`)
- CLI command → Bridge orchestration: runs (evidence: `internal/cli/root.go`)
- Settings validation → Filter rules: checks routes (evidence: `internal/cli/config.go`)
- Settings validation → Subject conversion: checks subjects (evidence: `internal/cli/config.go`)
- Bridge orchestration → Stream setup: sets up streams (evidence: `internal/bridge/bridge.go`)
- Bridge orchestration → Route lifecycle: starts routes (evidence: `internal/bridge/bridge.go`)
- Bridge orchestration → Route statistics: reports counters (evidence: `internal/bridge/bridge.go`)
- Route lifecycle → MQTT client: connects (evidence: `internal/bridge/route.go`)
- Route lifecycle → Message queue: creates (evidence: `internal/bridge/route.go`)
- Route lifecycle → Publish and retry: starts (evidence: `internal/bridge/route.go`)
- MQTT client → Broker interface: implements (evidence: `internal/broker/paho.go`)
- MQTT client → MQTT TLS: configures TLS
- MQTT client → MQTT broker: subscribes (evidence: `internal/broker/paho.go`)
- MQTT broker → MQTT client: delivers messages (evidence: `README.md`)
- Publish and retry → Message queue: drains messages (evidence: `internal/bridge/publisher.go`)
- Publish and retry → Subject conversion: converts topics (evidence: `internal/bridge/publisher.go`)
- Publish and retry → NATS JetStream: publishes (evidence: `internal/bridge/publisher.go`)
- Stream setup → NATS JetStream: creates streams (evidence: `README.md`)
- Route statistics → Publish and retry: reads counters
