# donaldzou/wgdashboard architecture

> Architecture diagram of the GitHub repository donaldzou/wgdashboard, 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/donaldzou/wgdashboard
- Repository: https://github.com/donaldzou/wgdashboard

## Overview

WGDashboard is a web application for managing WireGuard configurations and peers, with separate administrator and end-user interfaces. An administrator uses the dashboard to inspect and change configurations; the server-side API delegates configuration operations to WireGuard management code, which interacts with WireGuard and persists dashboard data. The end-user portal supports account access and peer configuration. The README establishes the product purpose and major features; where frontend-to-API wiring or unsampled subsystem behavior is not shown, those links are marked unverified.

Main entry points: [`src/dashboard.py`](https://github.com/donaldzou/wgdashboard/blob/main/src/dashboard.py) (Dashboard API), [`src/modules/WireguardConfiguration.py`](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/WireguardConfiguration.py) (Configuration manager), [`src/modules/DashboardClients.py`](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardClients.py) (Client accounts), [`src/client.py`](https://github.com/donaldzou/wgdashboard/blob/main/src/client.py) (Client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Web interfaces"]
  node_admin["Admin dashboard<br/>[App.vue]"]
  node_portal["Client portal<br/>[App.vue]"]
end

subgraph group_api["HTTP services"]
  node_dashboard_api["Dashboard API<br/>[dashboard.py]"]
  node_client_api["Client API<br/>[client.py]"]
end

subgraph group_vpn["WireGuard management"]
  node_wg_config["Configuration manager"]
  node_amnezia["Amnezia support"]
  node_peer["Peer management<br/>[Peer.py]"]
  node_jobs["Peer jobs<br/>[PeerJobs.py]"]
end

subgraph group_accounts["Accounts and sharing"]
  node_clients["Client accounts"]
  node_assignments["Peer assignments"]
  node_totp["TOTP tokens"]
  node_sharing["Peer sharing<br/>[PeerShareLinks.py]"]
end

subgraph group_platform["Persistence and integrations"]
  node_config["Dashboard settings<br/>[DashboardConfig.py]"]
  node_database[("Dashboard database")]
  node_webhooks["Webhooks"]
  node_status["System status<br/>[SystemStatus.py]"]
  node_email["Email delivery<br/>[Email.py]"]
end

node_administrator(("Administrator"))
node_client_user(("Client user"))
node_wireguard{{"WireGuard service"}}
node_email_service{{"Email service"}}
node_oidc_provider{{"OIDC provider"}}

node_administrator -->|"uses"| node_admin
node_client_user -->|"uses"| node_portal
node_admin -.->|"calls API"| node_dashboard_api
node_portal -.->|"calls API"| node_client_api
node_dashboard_api -->|"manages configs"| node_wg_config
node_dashboard_api -->|"routes operations"| node_amnezia
node_dashboard_api -->|"handles jobs"| node_jobs
node_dashboard_api -->|"handles sharing"| node_sharing
node_dashboard_api -->|"handles clients"| node_clients
node_dashboard_api -->|"uses hooks"| node_webhooks
node_dashboard_api -->|"reports status"| node_status
node_client_api -->|"authenticates users"| node_clients
node_client_api -->|"checks settings"| node_config
node_client_api -->|"sends reset email"| node_email
node_wg_config -.->|"controls VPN"| node_wireguard
node_wg_config -->|"manages peers"| node_peer
node_wg_config -->|"uses peer jobs"| node_jobs
node_wg_config -->|"uses share links"| node_sharing
node_wg_config -->|"fires hooks"| node_webhooks
node_amnezia -->|"uses configuration"| node_wg_config
node_clients -->|"uses assignments"| node_assignments
node_clients -->|"uses tokens"| node_totp
node_clients -.->|"authenticates via OIDC"| node_oidc_provider
node_jobs -->|"looks up peers"| node_wg_config
node_jobs -->|"reads and writes"| node_database
node_sharing -->|"reads and writes"| node_database
node_config -->|"reads and writes"| node_database
node_webhooks -->|"stores hook state"| node_database
node_webhooks -->|"posts webhook"| node_email_service
node_email -.->|"sends messages"| node_email_service

click node_admin "https://github.com/donaldzou/wgdashboard/blob/main/src/static/app/src/App.vue"
click node_portal "https://github.com/donaldzou/wgdashboard/blob/main/src/static/client/src/App.vue"
click node_dashboard_api "https://github.com/donaldzou/wgdashboard/blob/main/src/dashboard.py"
click node_client_api "https://github.com/donaldzou/wgdashboard/blob/main/src/client.py"
click node_wg_config "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/WireguardConfiguration.py"
click node_amnezia "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/AmneziaConfiguration.py"
click node_peer "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/Peer.py"
click node_jobs "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/PeerJobs.py"
click node_clients "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardClients.py"
click node_assignments "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardClientsPeerAssignment.py"
click node_totp "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardClientsTOTP.py"
click node_sharing "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/PeerShareLinks.py"
click node_config "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardConfig.py"
click node_database "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DatabaseConnection.py"
click node_webhooks "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardWebHooks.py"
click node_status "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/SystemStatus.py"
click node_email "https://github.com/donaldzou/wgdashboard/blob/main/src/modules/Email.py"

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_admin,node_portal,node_client_user toneBlue
class node_dashboard_api,node_client_api toneAmber
class node_wg_config,node_amnezia,node_peer,node_jobs toneMint
class node_clients,node_assignments,node_totp,node_sharing toneRose
class node_config,node_database,node_webhooks,node_status,node_email,node_administrator,node_wireguard,node_email_service,node_oidc_provider toneIndigo
```

## Components

### Web interfaces

- [Admin dashboard](https://github.com/donaldzou/wgdashboard/blob/main/src/static/app/src/App.vue): `src/static/app/src/App.vue`
- [Client portal](https://github.com/donaldzou/wgdashboard/blob/main/src/static/client/src/App.vue): `src/static/client/src/App.vue`

### HTTP services

- [Dashboard API](https://github.com/donaldzou/wgdashboard/blob/main/src/dashboard.py): `src/dashboard.py`
- [Client API](https://github.com/donaldzou/wgdashboard/blob/main/src/client.py): `src/client.py`

### WireGuard management

- [Configuration manager](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/WireguardConfiguration.py): `src/modules/WireguardConfiguration.py`
- [Amnezia support](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/AmneziaConfiguration.py): `src/modules/AmneziaConfiguration.py`
- [Peer management](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/Peer.py): `src/modules/Peer.py`
- [Peer jobs](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/PeerJobs.py): `src/modules/PeerJobs.py`

### Accounts and sharing

- [Client accounts](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardClients.py): `src/modules/DashboardClients.py`
- [Peer assignments](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardClientsPeerAssignment.py): `src/modules/DashboardClientsPeerAssignment.py`
- [TOTP tokens](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardClientsTOTP.py): `src/modules/DashboardClientsTOTP.py`
- [Peer sharing](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/PeerShareLinks.py): `src/modules/PeerShareLinks.py`

### Persistence and integrations

- [Dashboard settings](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardConfig.py): `src/modules/DashboardConfig.py`
- [Dashboard database](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DatabaseConnection.py): `src/modules/DatabaseConnection.py`
- [Webhooks](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/DashboardWebHooks.py): `src/modules/DashboardWebHooks.py`
- [System status](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/SystemStatus.py): `src/modules/SystemStatus.py`
- [Email delivery](https://github.com/donaldzou/wgdashboard/blob/main/src/modules/Email.py): `src/modules/Email.py`

### Other components

- **Administrator**
- **Client user**
- **WireGuard service**
- **Email service**
- **OIDC provider**

## Connections

- Administrator → Admin dashboard: uses
- Client user → Client portal: uses
- Admin dashboard → Dashboard API: calls API
- Client portal → Client API: calls API
- Dashboard API → Configuration manager: manages configs (evidence: `src/dashboard.py`)
- Dashboard API → Amnezia support: routes operations (evidence: `src/dashboard.py`)
- Dashboard API → Peer jobs: handles jobs (evidence: `src/dashboard.py`)
- Dashboard API → Peer sharing: handles sharing (evidence: `src/dashboard.py`)
- Dashboard API → Client accounts: handles clients (evidence: `src/dashboard.py`)
- Dashboard API → Webhooks: uses hooks (evidence: `src/dashboard.py`)
- Dashboard API → System status: reports status (evidence: `src/dashboard.py`)
- Client API → Client accounts: authenticates users (evidence: `src/client.py`)
- Client API → Dashboard settings: checks settings (evidence: `src/client.py`)
- Client API → Email delivery: sends reset email (evidence: `src/client.py`)
- Configuration manager → WireGuard service: controls VPN
- Configuration manager → Peer management: manages peers (evidence: `src/modules/WireguardConfiguration.py`)
- Configuration manager → Peer jobs: uses peer jobs (evidence: `src/modules/WireguardConfiguration.py`)
- Configuration manager → Peer sharing: uses share links (evidence: `src/modules/WireguardConfiguration.py`)
- Configuration manager → Webhooks: fires hooks (evidence: `src/modules/WireguardConfiguration.py`)
- Amnezia support → Configuration manager: uses configuration (evidence: `src/modules/AmneziaConfiguration.py`)
- Client accounts → Peer assignments: uses assignments (evidence: `src/modules/DashboardClients.py`)
- Client accounts → TOTP tokens: uses tokens (evidence: `src/modules/DashboardClients.py`)
- Client accounts → OIDC provider: authenticates via OIDC
- Peer jobs → Configuration manager: looks up peers (evidence: `src/modules/PeerJobs.py`)
- Peer jobs → Dashboard database: reads and writes (evidence: `src/modules/PeerJobs.py`)
- Peer sharing → Dashboard database: reads and writes (evidence: `src/modules/PeerShareLinks.py`)
- Dashboard settings → Dashboard database: reads and writes (evidence: `src/modules/DashboardConfig.py`)
- Webhooks → Dashboard database: stores hook state (evidence: `src/modules/DashboardWebHooks.py`)
- Webhooks → Email service: posts webhook (evidence: `src/modules/DashboardWebHooks.py`)
- Email delivery → Email service: sends messages
