# stuffam/drawbridge architecture

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

- Interactive diagram: https://gitdiagram.com/stuffam/drawbridge
- Repository: https://github.com/stuffam/drawbridge

## Overview

Drawbridge manages a WireGuard VPN through a self-hosted web UI, CLI, and authenticated API. The main workflow is a user request entering an API or local control socket, passing through shared management logic, being persisted, and—when configuration changes—reconciled with the host tunnel and firewall. The product also covers authentication, client configuration, traffic and DNS visibility, backups, diagnostics, certificates, and event history. Several links reflect the README or SOURCE INDEX; unsampled API and daemon wiring is not inferred beyond those references.

Main entry points: [`internal/service/service.go`](https://github.com/stuffam/drawbridge/blob/main/internal/service/service.go) (Management service), [`internal/reconcile/reconcile.go`](https://github.com/stuffam/drawbridge/blob/main/internal/reconcile/reconcile.go) (Host reconciliation), [`internal/api/handlers.go`](https://github.com/stuffam/drawbridge/blob/main/internal/api/handlers.go) (Web API), [`cmd/drawbridge/client_cmd.go`](https://github.com/stuffam/drawbridge/blob/main/cmd/drawbridge/client_cmd.go) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[client_cmd.go]"]
  node_web["Web UI<br/>[+page.svelte]"]
  node_webapi["Web API<br/>[handlers.go]"]
  node_control["Local control API<br/>[server.go]"]
  node_controlclient["Control client<br/>[client.go]"]
end

subgraph group_management["Management services"]
  node_service["Management service<br/>[service.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_views["Shared API views<br/>[views.go]"]
  node_configs["Client configs<br/>[clientconf.go]"]
  node_diagnostics["Host diagnostics<br/>[checks.go]"]
  node_adguard["AdGuard integration<br/>[adguard.go]"]
end

subgraph group_runtime["VPN runtime"]
  node_reconcile["Host reconciliation<br/>[reconcile.go]"]
  node_wireguard["WireGuard tunnel<br/>[wg.go]"]
  node_firewall["Firewall rules<br/>[firewall.go]"]
end

subgraph group_state["State and integrations"]
  node_model["Domain model<br/>[model.go]"]
  node_store[("Persistent state<br/>[store.go]")]
  node_traffic[("Traffic history<br/>[traffic.go]")]
  node_backup["Backup and restore<br/>[backup.go]"]
  node_tls["TLS certificates<br/>[tlscert.go]"]
  node_ipam["Address allocation<br/>[ipam.go]"]
end

node_admin(("Administrator"))

node_admin -->|"runs commands"| node_cli
node_admin -->|"manages VPN"| node_web
node_cli -->|"invokes"| node_controlclient
node_controlclient -->|"calls over socket"| node_control
node_web -->|"uses API"| node_webapi
node_control -->|"calls"| node_service
node_webapi -->|"calls"| node_service
node_webapi -->|"formats responses"| node_views
node_control -->|"formats responses"| node_views
node_service -->|"reads and writes"| node_store
node_service -->|"applies changes"| node_reconcile
node_service -->|"uses"| node_auth
node_service -->|"runs checks"| node_diagnostics
node_service -->|"renders configs"| node_configs
node_service -->|"uses domain types"| node_model
node_service -.->|"integrates DNS"| node_adguard
node_reconcile -->|"configures tunnel"| node_wireguard
node_reconcile -->|"configures rules"| node_firewall
node_reconcile -->|"reads settings"| node_model
node_model -->|"allocates addresses"| node_ipam
node_service -.->|"records traffic"| node_traffic
node_service -.->|"creates backups"| node_backup
node_service -.->|"manages certificates"| node_tls
node_cli -->|"displays client config"| node_configs
node_web -->|"renames clients through"| node_webapi

click node_cli "https://github.com/stuffam/drawbridge/blob/main/cmd/drawbridge/client_cmd.go"
click node_web "https://github.com/stuffam/drawbridge/blob/main/web/src/routes/(app)/%2Bpage.svelte"
click node_webapi "https://github.com/stuffam/drawbridge/blob/main/internal/api/handlers.go"
click node_control "https://github.com/stuffam/drawbridge/blob/main/internal/control/server.go"
click node_controlclient "https://github.com/stuffam/drawbridge/blob/main/internal/control/client.go"
click node_service "https://github.com/stuffam/drawbridge/blob/main/internal/service/service.go"
click node_auth "https://github.com/stuffam/drawbridge/blob/main/internal/service/auth.go"
click node_views "https://github.com/stuffam/drawbridge/blob/main/internal/views/views.go"
click node_configs "https://github.com/stuffam/drawbridge/blob/main/internal/clientconf/clientconf.go"
click node_diagnostics "https://github.com/stuffam/drawbridge/blob/main/internal/diag/checks.go"
click node_adguard "https://github.com/stuffam/drawbridge/blob/main/internal/adguard/adguard.go"
click node_reconcile "https://github.com/stuffam/drawbridge/blob/main/internal/reconcile/reconcile.go"
click node_wireguard "https://github.com/stuffam/drawbridge/blob/main/internal/wg/wg.go"
click node_firewall "https://github.com/stuffam/drawbridge/blob/main/internal/firewall/firewall.go"
click node_model "https://github.com/stuffam/drawbridge/blob/main/internal/model/model.go"
click node_store "https://github.com/stuffam/drawbridge/blob/main/internal/store/store.go"
click node_traffic "https://github.com/stuffam/drawbridge/blob/main/internal/store/traffic.go"
click node_backup "https://github.com/stuffam/drawbridge/blob/main/internal/backup/backup.go"
click node_tls "https://github.com/stuffam/drawbridge/blob/main/internal/tlscert/tlscert.go"
click node_ipam "https://github.com/stuffam/drawbridge/blob/main/internal/ipam/ipam.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_web,node_webapi,node_control,node_controlclient toneBlue
class node_service,node_auth,node_views,node_configs,node_diagnostics,node_adguard toneAmber
class node_reconcile,node_wireguard,node_firewall toneMint
class node_model,node_store,node_traffic,node_backup,node_tls,node_ipam toneRose
class node_admin toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/stuffam/drawbridge/blob/main/cmd/drawbridge/client_cmd.go): `cmd/drawbridge/client_cmd.go`
- [Web UI](https://github.com/stuffam/drawbridge/blob/main/web/src/routes/(app)/%2Bpage.svelte): `web/src/routes/(app)/+page.svelte`
- [Web API](https://github.com/stuffam/drawbridge/blob/main/internal/api/handlers.go): `internal/api/handlers.go`
- [Local control API](https://github.com/stuffam/drawbridge/blob/main/internal/control/server.go): `internal/control/server.go`
- [Control client](https://github.com/stuffam/drawbridge/blob/main/internal/control/client.go): `internal/control/client.go`

### Management services

- [Management service](https://github.com/stuffam/drawbridge/blob/main/internal/service/service.go): `internal/service/service.go`
- [Authentication](https://github.com/stuffam/drawbridge/blob/main/internal/service/auth.go): `internal/service/auth.go`
- [Shared API views](https://github.com/stuffam/drawbridge/blob/main/internal/views/views.go): `internal/views/views.go`
- [Client configs](https://github.com/stuffam/drawbridge/blob/main/internal/clientconf/clientconf.go): `internal/clientconf/clientconf.go`
- [Host diagnostics](https://github.com/stuffam/drawbridge/blob/main/internal/diag/checks.go): `internal/diag/checks.go`
- [AdGuard integration](https://github.com/stuffam/drawbridge/blob/main/internal/adguard/adguard.go): `internal/adguard/adguard.go`

### VPN runtime

- [Host reconciliation](https://github.com/stuffam/drawbridge/blob/main/internal/reconcile/reconcile.go): `internal/reconcile/reconcile.go`
- [WireGuard tunnel](https://github.com/stuffam/drawbridge/blob/main/internal/wg/wg.go): `internal/wg/wg.go`
- [Firewall rules](https://github.com/stuffam/drawbridge/blob/main/internal/firewall/firewall.go): `internal/firewall/firewall.go`

### State and integrations

- [Domain model](https://github.com/stuffam/drawbridge/blob/main/internal/model/model.go): `internal/model/model.go`
- [Persistent state](https://github.com/stuffam/drawbridge/blob/main/internal/store/store.go): `internal/store/store.go`
- [Traffic history](https://github.com/stuffam/drawbridge/blob/main/internal/store/traffic.go): `internal/store/traffic.go`
- [Backup and restore](https://github.com/stuffam/drawbridge/blob/main/internal/backup/backup.go): `internal/backup/backup.go`
- [TLS certificates](https://github.com/stuffam/drawbridge/blob/main/internal/tlscert/tlscert.go): `internal/tlscert/tlscert.go`
- [Address allocation](https://github.com/stuffam/drawbridge/blob/main/internal/ipam/ipam.go): `internal/ipam/ipam.go`

### Other components

- **Administrator**

## Connections

- Administrator → CLI commands: runs commands (evidence: `README.md`)
- Administrator → Web UI: manages VPN (evidence: `README.md`)
- CLI commands → Control client: invokes (evidence: `cmd/drawbridge/client_cmd.go`)
- Control client → Local control API: calls over socket (evidence: `internal/control/client.go`)
- Web UI → Web API: uses API (evidence: `README.md`)
- Local control API → Management service: calls (evidence: `internal/control/server.go`)
- Web API → Management service: calls (evidence: `internal/api/handlers.go`)
- Web API → Shared API views: formats responses (evidence: `internal/api/handlers.go`)
- Local control API → Shared API views: formats responses (evidence: `internal/control/server.go`)
- Management service → Persistent state: reads and writes (evidence: `internal/service/service.go`)
- Management service → Host reconciliation: applies changes (evidence: `internal/service/service.go`)
- Management service → Authentication: uses (evidence: `internal/service/auth.go`)
- Management service → Host diagnostics: runs checks (evidence: `internal/service/service.go`)
- Management service → Client configs: renders configs (evidence: `internal/service/service.go`)
- Management service → Domain model: uses domain types (evidence: `internal/service/service.go`)
- Management service → AdGuard integration: integrates DNS
- Host reconciliation → WireGuard tunnel: configures tunnel (evidence: `internal/reconcile/reconcile.go`)
- Host reconciliation → Firewall rules: configures rules (evidence: `internal/reconcile/reconcile.go`)
- Host reconciliation → Domain model: reads settings (evidence: `internal/reconcile/reconcile.go`)
- Domain model → Address allocation: allocates addresses (evidence: `internal/model/model.go`)
- Management service → Traffic history: records traffic
- Management service → Backup and restore: creates backups
- Management service → TLS certificates: manages certificates
- CLI commands → Client configs: displays client config (evidence: `cmd/drawbridge/client_cmd.go`)
- Web UI → Web API: renames clients through
