# nishan-soni/k3s-zeroconf architecture

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

- Interactive diagram: https://gitdiagram.com/nishan-soni/k3s-zeroconf
- Repository: https://github.com/nishan-soni/k3s-zeroconf

## Overview

k3s-zeroconf is a small CLI for discovering local k3s agents and pairing them with a cluster. The main workflow starts an agent that advertises itself over mDNS and waits for a join request; an operator discovers and adds it, after which the agent hands off to k3s. The map includes firewall setup and shared pairing data. Edges are limited to relationships visible in the excerpts; no README was provided.

Main entry points: [`internal/agent/run.go`](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/run.go) (Agent workflow), [`internal/master/discover.go`](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/master/discover.go) (Discover and add), [`cmd/main.go`](https://github.com/nishan-soni/k3s-zeroconf/blob/main/cmd/main.go) (k3z commands), [`internal/agent/server.go`](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/server.go) (Pairing HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and orchestration"]
  node_cli["k3z commands<br/>[main.go]"]
end

subgraph group_agent["Agent pairing"]
  node_agent_run["Agent workflow<br/>[run.go]"]
  node_pairing_server["Pairing HTTP server<br/>[server.go]"]
  node_mdns_register["mDNS registration<br/>[mdns.go]"]
  node_k3s_handoff["k3s handoff<br/>[k3sagent.go]"]
end

subgraph group_master["Discovery and joining"]
  node_master_discovery["Discover and add<br/>[discover.go]"]
end

subgraph group_shared["Shared protocol"]
  node_pairing_info["Pairing data<br/>[types.go]"]
  node_shared_settings["Network settings<br/>[constants.go]"]
  node_outbound_ip["Outbound IP helper<br/>[utils.go]"]
end

node_operator(("Operator"))
node_network_discovery(("mDNS network"))
node_k3s["k3s agent"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"starts agent"| node_agent_run
node_cli -->|"discovers or adds"| node_master_discovery
node_cli -->|"gets address"| node_outbound_ip
node_agent_run -->|"starts server"| node_pairing_server
node_agent_run -->|"registers agent"| node_mdns_register
node_agent_run -->|"hands off flags"| node_k3s_handoff
node_pairing_server -->|"decodes request"| node_pairing_info
node_pairing_server -->|"sends join data"| node_agent_run
node_mdns_register -->|"advertises service"| node_network_discovery
node_master_discovery -->|"browses or looks up"| node_network_discovery
node_master_discovery -->|"posts join data"| node_pairing_server
node_master_discovery -->|"builds join data"| node_pairing_info
node_k3s_handoff -->|"executes agent"| node_k3s
node_mdns_register -->|"gets address"| node_outbound_ip
node_agent_run -->|"uses port"| node_shared_settings
node_master_discovery -->|"uses service settings"| node_shared_settings
node_k3s_handoff -->|"opens configured ports"| node_shared_settings

click node_cli "https://github.com/nishan-soni/k3s-zeroconf/blob/main/cmd/main.go"
click node_agent_run "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/run.go"
click node_pairing_server "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/server.go"
click node_mdns_register "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/mdns.go"
click node_k3s_handoff "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/k3sagent.go"
click node_master_discovery "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/master/discover.go"
click node_pairing_info "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/common/types.go"
click node_shared_settings "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/common/constants.go"
click node_outbound_ip "https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/common/utils.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 toneBlue
class node_agent_run,node_pairing_server,node_mdns_register,node_k3s_handoff toneAmber
class node_master_discovery toneMint
class node_pairing_info,node_shared_settings,node_outbound_ip toneRose
class node_operator,node_network_discovery,node_k3s toneIndigo
```

## Components

### CLI and orchestration

- [k3z commands](https://github.com/nishan-soni/k3s-zeroconf/blob/main/cmd/main.go): `cmd/main.go`

### Agent pairing

- [Agent workflow](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/run.go): `internal/agent/run.go`
- [Pairing HTTP server](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/server.go): `internal/agent/server.go`
- [mDNS registration](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/mdns.go): `internal/agent/mdns.go`
- [k3s handoff](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/agent/k3sagent.go): `internal/agent/k3sagent.go`

### Discovery and joining

- [Discover and add](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/master/discover.go): `internal/master/discover.go`

### Shared protocol

- [Pairing data](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/common/types.go): `internal/common/types.go`
- [Network settings](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/common/constants.go): `internal/common/constants.go`
- [Outbound IP helper](https://github.com/nishan-soni/k3s-zeroconf/blob/main/internal/common/utils.go): `internal/common/utils.go`

### Other components

- **Operator**
- **mDNS network**
- **k3s agent**

## Connections

- Operator → k3z commands: runs commands (evidence: `cmd/main.go`)
- k3z commands → Agent workflow: starts agent (evidence: `cmd/main.go`)
- k3z commands → Discover and add: discovers or adds (evidence: `cmd/main.go`)
- k3z commands → Outbound IP helper: gets address (evidence: `cmd/main.go`)
- Agent workflow → Pairing HTTP server: starts server (evidence: `internal/agent/run.go`)
- Agent workflow → mDNS registration: registers agent (evidence: `internal/agent/run.go`)
- Agent workflow → k3s handoff: hands off flags (evidence: `internal/agent/run.go`)
- Pairing HTTP server → Pairing data: decodes request (evidence: `internal/agent/server.go`)
- Pairing HTTP server → Agent workflow: sends join data (evidence: `internal/agent/run.go`)
- mDNS registration → mDNS network: advertises service (evidence: `internal/agent/mdns.go`)
- Discover and add → mDNS network: browses or looks up (evidence: `internal/master/discover.go`)
- Discover and add → Pairing HTTP server: posts join data (evidence: `internal/master/discover.go`)
- Discover and add → Pairing data: builds join data (evidence: `internal/master/discover.go`)
- k3s handoff → k3s agent: executes agent (evidence: `internal/agent/k3sagent.go`)
- mDNS registration → Outbound IP helper: gets address (evidence: `internal/agent/mdns.go`)
- Agent workflow → Network settings: uses port
- Discover and add → Network settings: uses service settings (evidence: `internal/master/discover.go`)
- k3s handoff → Network settings: opens configured ports (evidence: `internal/agent/k3sagent.go`)
