# sniksax/openward architecture

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

- Interactive diagram: https://gitdiagram.com/sniksax/openward
- Repository: https://github.com/sniksax/openward

## Overview

OpenWard is a WireGuard-based, zone-segmented network access manager. An administrator signs in to the dashboard, provisions peers with a role and configuration, and monitors or revokes them; users can also claim accounts from an active peer. The Go service exposes the API, persists users and peers in SQLite, and regenerates the gateway’s WireGuard configuration as peers change. The README documents the zone firewall policy and single-origin static dashboard serving. Several backend helpers and dashboard pages are unsampled, so their internal links are omitted where not evidenced.

Main entry points: [`backend/src/routers/main.router.go`](https://github.com/sniksax/openward/blob/main/backend/src/routers/main.router.go) (API Router), [`frontend/lib/api.ts`](https://github.com/sniksax/openward/blob/main/frontend/lib/api.ts) (API Client), [`backend/src/controllers/users.controller.go`](https://github.com/sniksax/openward/blob/main/backend/src/controllers/users.controller.go) (User Controller), [`backend/src/services/peers.service.go`](https://github.com/sniksax/openward/blob/main/backend/src/services/peers.service.go) (Peer Lifecycle Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Management Dashboard"]
  node_login["Login Page<br/>[page.tsx]"]
  node_api_client["API Client<br/>[api.ts]"]
  node_deploy["Peer Deployment<br/>[page.tsx]"]
  node_peer_list["Peer Management<br/>[page.tsx]"]
  node_stats_hook["Live Stats Hook<br/>[use-live-stats.ts]"]
  node_dashboard["Network Overview<br/>[page.tsx]"]
  node_users_page["User Management<br/>[page.tsx]"]
  node_static_dashboard["Static Dashboard Files"]
end

subgraph group_api["API and Identity"]
  node_http_server["HTTP Server<br/>[main.go]"]
  node_router["API Router<br/>[main.router.go]"]
  node_user_controller["User Controller"]
  node_auth_service["Account Services<br/>[users.service.go]"]
  node_user_store[("User Repository<br/>[users.db.go]")]
end

subgraph group_peers["Peer Lifecycle"]
  node_peer_controller["Peer Controller"]
  node_peer_service["Peer Lifecycle Service<br/>[peers.service.go]"]
  node_peer_store[("Peer Repository<br/>[peers.db.go]")]
end

subgraph group_network["Gateway Network"]
  node_config_sync["WireGuard Config Sync"]
  node_zone_policy["Zone Firewall Policy"]
  node_gateway{{"WireGuard Gateway"}}
end

node_admin(("Administrator"))

node_admin -->|"signs in"| node_login
node_login -->|"requests login"| node_api_client
node_deploy -->|"creates peer"| node_api_client
node_peer_list -->|"loads peers"| node_api_client
node_peer_list -->|"uses live stats"| node_stats_hook
node_admin -.->|"provisions access"| node_deploy
node_admin -.->|"reviews network"| node_dashboard
node_admin -.->|"manages users"| node_users_page
node_http_server -->|"registers routes"| node_router
node_router -->|"routes peer requests"| node_peer_controller
node_router -->|"routes user requests"| node_user_controller
node_router -->|"serves files"| node_static_dashboard
node_user_controller -->|"authenticates accounts"| node_auth_service
node_user_controller -->|"reads users"| node_user_store
node_peer_controller -->|"handles peer actions"| node_peer_service
node_peer_service -->|"stores peer records"| node_peer_store
node_peer_service -->|"syncs configuration"| node_config_sync
node_config_sync -.->|"reads active peers"| node_peer_store
node_config_sync -->|"writes wg0 config"| node_gateway
node_zone_policy -->|"enforces segmentation"| node_gateway
node_api_client -.->|"calls API"| node_http_server

click node_login "https://github.com/sniksax/openward/blob/main/frontend/app/page.tsx"
click node_api_client "https://github.com/sniksax/openward/blob/main/frontend/lib/api.ts"
click node_deploy "https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/dashboard/deploy/page.tsx"
click node_peer_list "https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/peers/page.tsx"
click node_stats_hook "https://github.com/sniksax/openward/blob/main/frontend/hooks/use-live-stats.ts"
click node_dashboard "https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/dashboard/page.tsx"
click node_users_page "https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/dashboard/users/page.tsx"
click node_http_server "https://github.com/sniksax/openward/blob/main/backend/src/main.go"
click node_router "https://github.com/sniksax/openward/blob/main/backend/src/routers/main.router.go"
click node_user_controller "https://github.com/sniksax/openward/blob/main/backend/src/controllers/users.controller.go"
click node_auth_service "https://github.com/sniksax/openward/blob/main/backend/src/services/users.service.go"
click node_peer_controller "https://github.com/sniksax/openward/blob/main/backend/src/controllers/peers.controller.go"
click node_peer_service "https://github.com/sniksax/openward/blob/main/backend/src/services/peers.service.go"
click node_peer_store "https://github.com/sniksax/openward/blob/main/backend/src/db/peers.db.go"
click node_user_store "https://github.com/sniksax/openward/blob/main/backend/src/db/users.db.go"
click node_config_sync "https://github.com/sniksax/openward/tree/main/backend/src/services"
click node_zone_policy "https://github.com/sniksax/openward/tree/main/backend/src/services"
click node_static_dashboard "https://github.com/sniksax/openward/tree/main/frontend"

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_login,node_api_client,node_deploy,node_peer_list,node_stats_hook,node_dashboard,node_users_page,node_static_dashboard toneBlue
class node_http_server,node_router,node_user_controller,node_auth_service,node_user_store toneAmber
class node_peer_controller,node_peer_service,node_peer_store toneMint
class node_config_sync,node_zone_policy,node_gateway toneRose
class node_admin toneIndigo
```

## Components

### Management Dashboard

- [Login Page](https://github.com/sniksax/openward/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [API Client](https://github.com/sniksax/openward/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Peer Deployment](https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/dashboard/deploy/page.tsx): `frontend/app/(dashboard)/dashboard/deploy/page.tsx`
- [Peer Management](https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/peers/page.tsx): `frontend/app/(dashboard)/peers/page.tsx`
- [Live Stats Hook](https://github.com/sniksax/openward/blob/main/frontend/hooks/use-live-stats.ts): `frontend/hooks/use-live-stats.ts`
- [Network Overview](https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/dashboard/page.tsx): `frontend/app/(dashboard)/dashboard/page.tsx`
- [User Management](https://github.com/sniksax/openward/blob/main/frontend/app/(dashboard)/dashboard/users/page.tsx): `frontend/app/(dashboard)/dashboard/users/page.tsx`
- [Static Dashboard Files](https://github.com/sniksax/openward/tree/main/frontend): `frontend`

### API and Identity

- [HTTP Server](https://github.com/sniksax/openward/blob/main/backend/src/main.go): `backend/src/main.go`
- [API Router](https://github.com/sniksax/openward/blob/main/backend/src/routers/main.router.go): `backend/src/routers/main.router.go`
- [User Controller](https://github.com/sniksax/openward/blob/main/backend/src/controllers/users.controller.go): `backend/src/controllers/users.controller.go`
- [Account Services](https://github.com/sniksax/openward/blob/main/backend/src/services/users.service.go): `backend/src/services/users.service.go`
- [User Repository](https://github.com/sniksax/openward/blob/main/backend/src/db/users.db.go): `backend/src/db/users.db.go`

### Peer Lifecycle

- [Peer Controller](https://github.com/sniksax/openward/blob/main/backend/src/controllers/peers.controller.go): `backend/src/controllers/peers.controller.go`
- [Peer Lifecycle Service](https://github.com/sniksax/openward/blob/main/backend/src/services/peers.service.go): `backend/src/services/peers.service.go`
- [Peer Repository](https://github.com/sniksax/openward/blob/main/backend/src/db/peers.db.go): `backend/src/db/peers.db.go`

### Gateway Network

- [WireGuard Config Sync](https://github.com/sniksax/openward/tree/main/backend/src/services): `backend/src/services`
- [Zone Firewall Policy](https://github.com/sniksax/openward/tree/main/backend/src/services): `backend/src/services`
- **WireGuard Gateway**

### Other components

- **Administrator**

## Connections

- Administrator → Login Page: signs in (evidence: `frontend/app/page.tsx`)
- Login Page → API Client: requests login (evidence: `frontend/app/page.tsx`)
- Peer Deployment → API Client: creates peer (evidence: `frontend/app/(dashboard)/dashboard/deploy/page.tsx`)
- Peer Management → API Client: loads peers (evidence: `frontend/app/(dashboard)/peers/page.tsx`)
- Peer Management → Live Stats Hook: uses live stats (evidence: `frontend/app/(dashboard)/peers/page.tsx`)
- Administrator → Peer Deployment: provisions access
- Administrator → Network Overview: reviews network
- Administrator → User Management: manages users
- HTTP Server → API Router: registers routes (evidence: `backend/src/main.go`)
- API Router → Peer Controller: routes peer requests (evidence: `backend/src/routers/main.router.go`)
- API Router → User Controller: routes user requests (evidence: `backend/src/routers/main.router.go`)
- API Router → Static Dashboard Files: serves files (evidence: `backend/src/routers/main.router.go`)
- User Controller → Account Services: authenticates accounts (evidence: `backend/src/controllers/users.controller.go`)
- User Controller → User Repository: reads users (evidence: `backend/src/controllers/users.controller.go`)
- Peer Controller → Peer Lifecycle Service: handles peer actions (evidence: `backend/src/controllers/peers.controller.go`)
- Peer Lifecycle Service → Peer Repository: stores peer records (evidence: `backend/src/services/peers.service.go`)
- Peer Lifecycle Service → WireGuard Config Sync: syncs configuration (evidence: `backend/src/services/peers.service.go`)
- WireGuard Config Sync → Peer Repository: reads active peers (evidence: `README.md`)
- WireGuard Config Sync → WireGuard Gateway: writes wg0 config (evidence: `README.md`)
- Zone Firewall Policy → WireGuard Gateway: enforces segmentation (evidence: `README.md`)
- API Client → HTTP Server: calls API (evidence: `README.md`)
