# saprayworld/pigate architecture

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

- Interactive diagram: https://gitdiagram.com/saprayworld/pigate
- Repository: https://github.com/saprayworld/pigate

## Overview

PiGate is a web-administered Raspberry Pi firewall and gateway. Administrators use the React SPA to authenticate and manage network, DNS/DHCP, firewall, QoS, WAN failover, users, and system settings; the Go API coordinates configuration and statistics with SQLite and Linux networking/services. The README documents broad feature coverage, but sampled source is concentrated in routing, API setup, and frontend statistics/auth; unsampled subsystem links are therefore omitted or marked unverified rather than treated as observed calls.

Main entry points: [`backend/internal/kernel/interfaces.go`](https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/interfaces.go) (Kernel Interfaces), [`backend/internal/api/router.go`](https://github.com/saprayworld/pigate/blob/main/backend/internal/api/router.go) (HTTP API), [`frontend/src/App.tsx`](https://github.com/saprayworld/pigate/blob/main/frontend/src/App.tsx) (Admin SPA), [`backend/internal/service`](https://github.com/saprayworld/pigate/tree/main/backend/internal/service) (Network Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Administration UI"]
  node_spa["Admin SPA<br/>[App.tsx]"]
  node_authui["Session UI<br/>[authService.ts]"]
  node_routesui["Network Management<br/>[StaticRoutes.tsx]"]
  node_statsui["Statistics Views"]
  node_dnsui["DNS Management"]
end

subgraph group_api["API and Services"]
  node_http["HTTP API<br/>[router.go]"]
  node_handlers["Request Handlers<br/>[handlers.go]"]
  node_wanhandlers["WAN Handlers<br/>[wan_handlers.go]"]
  node_services["Network Services"]
  node_routing["Route Coordination<br/>[routing.go]"]
  node_dnsservice["DNS Services"]
  node_statistics["Traffic Statistics"]
  node_user["User Management"]
end

subgraph group_storage["Configuration Storage"]
  node_db[("SQLite Repositories<br/>[repository.go]")]
  node_models["Domain Models<br/>[types.go]"]
end

subgraph group_system["Linux Control"]
  node_kernel["Kernel Interfaces<br/>[interfaces.go]"]
  node_netlink["Network and Firewall<br/>[real_network.go]"]
  node_dnsruntime["DNS Runtime<br/>[dns_server.go]"]
  node_systemd["System Services"]
  node_logs[("RAM Log Buffer<br/>[ringbuffer.go]")]
end

node_admin(("Administrator"))
node_browser(("Browser"))

node_admin -->|"uses"| node_spa
node_browser -.->|"loads"| node_spa
node_spa -->|"checks session"| node_authui
node_authui -->|"auth requests"| node_http
node_spa -->|"routes to"| node_routesui
node_routesui -->|"fetches routes"| node_http
node_dnsui -->|"DNS requests"| node_http
node_statsui -->|"fetches statistics"| node_http
node_http -.->|"dispatches"| node_handlers
node_handlers -.->|"coordinates"| node_services
node_wanhandlers -.->|"coordinates WAN"| node_services
node_services -.->|"persists config"| node_db
node_services -.->|"controls system"| node_kernel
node_routing -->|"manages routes"| node_kernel
node_db -.->|"stores records"| node_models
node_kernel -.->|"implements control"| node_netlink
node_kernel -.->|"implements DNS"| node_dnsruntime
node_kernel -.->|"uses D-Bus"| node_systemd
node_statistics -.->|"buffers logs"| node_logs

click node_spa "https://github.com/saprayworld/pigate/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/saprayworld/pigate/blob/main/frontend/src/services/authService.ts"
click node_routesui "https://github.com/saprayworld/pigate/blob/main/frontend/src/pages/StaticRoutes.tsx"
click node_statsui "https://github.com/saprayworld/pigate/blob/main/frontend/src/services/statisticsService.ts"
click node_dnsui "https://github.com/saprayworld/pigate/blob/main/frontend/src/services/dnsServerService.ts"
click node_http "https://github.com/saprayworld/pigate/blob/main/backend/internal/api/router.go"
click node_handlers "https://github.com/saprayworld/pigate/blob/main/backend/internal/api/handlers.go"
click node_wanhandlers "https://github.com/saprayworld/pigate/blob/main/backend/internal/api/wan_handlers.go"
click node_services "https://github.com/saprayworld/pigate/tree/main/backend/internal/service"
click node_routing "https://github.com/saprayworld/pigate/blob/main/backend/internal/service/routing.go"
click node_dnsservice "https://github.com/saprayworld/pigate/tree/main/backend/internal/service"
click node_statistics "https://github.com/saprayworld/pigate/tree/main/backend/internal/service"
click node_user "https://github.com/saprayworld/pigate/tree/main/backend/internal/service"
click node_db "https://github.com/saprayworld/pigate/blob/main/backend/internal/db/repository.go"
click node_models "https://github.com/saprayworld/pigate/blob/main/backend/internal/model/types.go"
click node_kernel "https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/interfaces.go"
click node_netlink "https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/real_network.go"
click node_dnsruntime "https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/dns_server.go"
click node_systemd "https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/real_system_service.go"
click node_logs "https://github.com/saprayworld/pigate/blob/main/backend/internal/logs/ringbuffer.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_spa,node_authui,node_routesui,node_statsui,node_dnsui,node_browser toneBlue
class node_http,node_handlers,node_wanhandlers,node_services,node_routing,node_dnsservice,node_statistics,node_user toneAmber
class node_db,node_models toneMint
class node_kernel,node_netlink,node_dnsruntime,node_systemd,node_logs toneRose
class node_admin toneIndigo
```

## Components

### Administration UI

- [Admin SPA](https://github.com/saprayworld/pigate/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session UI](https://github.com/saprayworld/pigate/blob/main/frontend/src/services/authService.ts): `frontend/src/services/authService.ts`
- [Network Management](https://github.com/saprayworld/pigate/blob/main/frontend/src/pages/StaticRoutes.tsx): `frontend/src/pages/StaticRoutes.tsx`
- [Statistics Views](https://github.com/saprayworld/pigate/blob/main/frontend/src/services/statisticsService.ts): `frontend/src/services/statisticsService.ts`
- [DNS Management](https://github.com/saprayworld/pigate/blob/main/frontend/src/services/dnsServerService.ts): `frontend/src/services/dnsServerService.ts`

### API and Services

- [HTTP API](https://github.com/saprayworld/pigate/blob/main/backend/internal/api/router.go): `backend/internal/api/router.go`
- [Request Handlers](https://github.com/saprayworld/pigate/blob/main/backend/internal/api/handlers.go): `backend/internal/api/handlers.go`
- [WAN Handlers](https://github.com/saprayworld/pigate/blob/main/backend/internal/api/wan_handlers.go): `backend/internal/api/wan_handlers.go`
- [Network Services](https://github.com/saprayworld/pigate/tree/main/backend/internal/service): `backend/internal/service`
- [Route Coordination](https://github.com/saprayworld/pigate/blob/main/backend/internal/service/routing.go): `backend/internal/service/routing.go`
- [DNS Services](https://github.com/saprayworld/pigate/tree/main/backend/internal/service): `backend/internal/service`
- [Traffic Statistics](https://github.com/saprayworld/pigate/tree/main/backend/internal/service): `backend/internal/service`
- [User Management](https://github.com/saprayworld/pigate/tree/main/backend/internal/service): `backend/internal/service`

### Configuration Storage

- [SQLite Repositories](https://github.com/saprayworld/pigate/blob/main/backend/internal/db/repository.go): `backend/internal/db/repository.go`
- [Domain Models](https://github.com/saprayworld/pigate/blob/main/backend/internal/model/types.go): `backend/internal/model/types.go`

### Linux Control

- [Kernel Interfaces](https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/interfaces.go): `backend/internal/kernel/interfaces.go`
- [Network and Firewall](https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/real_network.go): `backend/internal/kernel/real_network.go`
- [DNS Runtime](https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/dns_server.go): `backend/internal/kernel/dns_server.go`
- [System Services](https://github.com/saprayworld/pigate/blob/main/backend/internal/kernel/real_system_service.go): `backend/internal/kernel/real_system_service.go`
- [RAM Log Buffer](https://github.com/saprayworld/pigate/blob/main/backend/internal/logs/ringbuffer.go): `backend/internal/logs/ringbuffer.go`

### Other components

- **Administrator**
- **Browser**

## Connections

- Administrator → Admin SPA: uses (evidence: `README.md`)
- Browser → Admin SPA: loads
- Admin SPA → Session UI: checks session (evidence: `frontend/src/App.tsx`)
- Session UI → HTTP API: auth requests (evidence: `frontend/src/services/authService.ts`)
- Admin SPA → Network Management: routes to (evidence: `frontend/src/App.tsx`)
- Network Management → HTTP API: fetches routes
- DNS Management → HTTP API: DNS requests (evidence: `frontend/src/services/dnsServerService.ts`)
- Statistics Views → HTTP API: fetches statistics (evidence: `frontend/src/services/statisticsService.ts`)
- HTTP API → Request Handlers: dispatches
- Request Handlers → Network Services: coordinates
- WAN Handlers → Network Services: coordinates WAN
- Network Services → SQLite Repositories: persists config
- Network Services → Kernel Interfaces: controls system
- Route Coordination → Kernel Interfaces: manages routes (evidence: `backend/internal/service/routing.go`)
- SQLite Repositories → Domain Models: stores records
- Kernel Interfaces → Network and Firewall: implements control
- Kernel Interfaces → DNS Runtime: implements DNS
- Kernel Interfaces → System Services: uses D-Bus
- Traffic Statistics → RAM Log Buffer: buffers logs
