# seriousm4x/upsnap architecture

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

- Interactive diagram: https://gitdiagram.com/seriousm4x/upsnap
- Repository: https://github.com/seriousm4x/upsnap

## Overview

UpSnap is a self-hosted Wake-on-LAN dashboard. A user manages devices and permissions in the web UI, then wakes, shuts down, or monitors devices; scheduled jobs automate status checks and wake/shutdown actions. The graph includes documented device discovery, port checks, IP tracking, user administration, logs, localization, and settings. Source excerpts confirm only selected backend and frontend calls, so other capability links are documented rather than inferred from co-location.

Main entry points: [`frontend/src/lib/stores/pocketbase.ts`](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/stores/pocketbase.ts) (PocketBase client), [`backend/pb/handlers.go`](https://github.com/seriousm4x/upsnap/blob/master/backend/pb/handlers.go) (Device handlers), [`backend/cronjobs/cronjobs.go`](https://github.com/seriousm4x/upsnap/blob/master/backend/cronjobs/cronjobs.go) (Scheduled jobs), [`frontend/src/routes/+layout.svelte`](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/%2Blayout.svelte) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_webapp["App shell<br/>[+layout.svelte]"]
  node_dashboard["Device dashboard<br/>[+page.svelte]"]
  node_deviceui["Device management<br/>[DeviceForm.svelte]"]
  node_scanui["Scan interface<br/>[NetworkScan.svelte]"]
  node_accountui["Account management<br/>[+page.svelte]"]
  node_adminui["Admin pages<br/>[+page.svelte]"]
  node_logsui["Log viewer<br/>[+page.svelte]"]
  node_settingsui["Settings<br/>[+page.svelte]"]
  node_localization["Localization<br/>[locale.ts]"]
  node_pbclient["PocketBase client<br/>[pocketbase.ts]"]
end

subgraph group_api["PocketBase application"]
  node_server["Application entry<br/>[main.go]"]
  node_pbsetup["PocketBase setup<br/>[pb.go]"]
  node_handlers["Device handlers<br/>[handlers.go]"]
  node_scanhandler["Scan handler"]
  node_middleware["Authorization middleware<br/>[middlewares.go]"]
  node_database[("PocketBase records")]
end

subgraph group_network["Network operations"]
  node_wol["Wake packets<br/>[magicpacket.go]"]
  node_devicecontrol["Device control<br/>[wake.go]"]
  node_shutdown["Shutdown commands<br/>[shutdown.go]"]
  node_ping["Reachability checks<br/>[ping.go]"]
  node_networkscan["Network discovery<br/>[scan.go]"]
  node_iptracking["IP tracking<br/>[iptracking.go]"]
end

subgraph group_automation["Automation"]
  node_cronjobs["Scheduled jobs<br/>[cronjobs.go]"]
  node_logs["Logging<br/>[logging.go]"]
end

node_user(("User"))
node_nmap["Nmap"]

node_user -->|"uses"| node_webapp
node_webapp -->|"loads auth and settings"| node_pbclient
node_webapp -.->|"renders routes"| node_dashboard
node_dashboard -->|"subscribes to records"| node_pbclient
node_deviceui -->|"saves devices"| node_pbclient
node_user -.->|"configures devices"| node_deviceui
node_user -.->|"discovers devices"| node_scanui
node_user -.->|"manages account"| node_accountui
node_user -.->|"administers users"| node_adminui
node_user -.->|"reviews logs"| node_logsui
node_user -.->|"configures app"| node_settingsui
node_webapp -->|"sets locale"| node_localization
node_server -->|"starts"| node_pbsetup
node_pbsetup -.->|"registers routes"| node_handlers
node_pbsetup -.->|"configures authorization"| node_middleware
node_pbsetup -.->|"uses records"| node_database
node_handlers -->|"reads and saves"| node_database
node_handlers -->|"controls devices"| node_devicecontrol
node_devicecontrol -->|"sends wake packet"| node_wol
node_handlers -.->|"requests shutdown"| node_shutdown
node_scanhandler -->|"reads scan settings"| node_database
node_scanhandler -->|"runs scan"| node_nmap
node_scanui -.->|"requests scan"| node_pbclient
node_pbclient -.->|"calls PocketBase API"| node_server
node_cronjobs -->|"reads and updates devices"| node_database
node_cronjobs -->|"checks status"| node_ping
node_cronjobs -->|"schedules sweeps"| node_iptracking
node_cronjobs -.->|"runs timed actions"| node_devicecontrol
node_iptracking -.->|"scans subnets"| node_nmap
node_logsui -->|"fetches logs"| node_pbclient
node_handlers -.->|"records events"| node_logs

click node_webapp "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/%2Blayout.svelte"
click node_dashboard "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/%2Bpage.svelte"
click node_deviceui "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/components/DeviceForm.svelte"
click node_scanui "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/components/NetworkScan.svelte"
click node_accountui "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/account/%2Bpage.svelte"
click node_adminui "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/users/%2Bpage.svelte"
click node_logsui "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/logs/%2Bpage.svelte"
click node_settingsui "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/settings/%2Bpage.svelte"
click node_localization "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/stores/locale.ts"
click node_pbclient "https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/stores/pocketbase.ts"
click node_server "https://github.com/seriousm4x/upsnap/blob/master/backend/main.go"
click node_pbsetup "https://github.com/seriousm4x/upsnap/blob/master/backend/pb/pb.go"
click node_handlers "https://github.com/seriousm4x/upsnap/blob/master/backend/pb/handlers.go"
click node_scanhandler "https://github.com/seriousm4x/upsnap/blob/master/backend/pb/handlerscan_linux.go"
click node_middleware "https://github.com/seriousm4x/upsnap/blob/master/backend/pb/middlewares.go"
click node_wol "https://github.com/seriousm4x/upsnap/blob/master/backend/networking/magicpacket.go"
click node_devicecontrol "https://github.com/seriousm4x/upsnap/blob/master/backend/networking/wake.go"
click node_shutdown "https://github.com/seriousm4x/upsnap/blob/master/backend/networking/shutdown.go"
click node_ping "https://github.com/seriousm4x/upsnap/blob/master/backend/networking/ping.go"
click node_networkscan "https://github.com/seriousm4x/upsnap/blob/master/backend/networking/scan.go"
click node_iptracking "https://github.com/seriousm4x/upsnap/blob/master/backend/iptracking/iptracking.go"
click node_cronjobs "https://github.com/seriousm4x/upsnap/blob/master/backend/cronjobs/cronjobs.go"
click node_logs "https://github.com/seriousm4x/upsnap/blob/master/backend/logging/logging.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_webapp,node_dashboard,node_deviceui,node_scanui,node_accountui,node_adminui,node_logsui,node_settingsui,node_localization,node_pbclient,node_user toneBlue
class node_server,node_pbsetup,node_handlers,node_scanhandler,node_middleware,node_database toneAmber
class node_wol,node_devicecontrol,node_shutdown,node_ping,node_networkscan,node_iptracking toneMint
class node_cronjobs,node_logs toneRose
class node_nmap toneIndigo
```

## Components

### Web interface

- [App shell](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/%2Blayout.svelte): `frontend/src/routes/+layout.svelte`
- [Device dashboard](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/%2Bpage.svelte): `frontend/src/routes/+page.svelte`
- [Device management](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/components/DeviceForm.svelte): `frontend/src/lib/components/DeviceForm.svelte`
- [Scan interface](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/components/NetworkScan.svelte): `frontend/src/lib/components/NetworkScan.svelte`
- [Account management](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/account/%2Bpage.svelte): `frontend/src/routes/account/+page.svelte`
- [Admin pages](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/users/%2Bpage.svelte): `frontend/src/routes/users/+page.svelte`
- [Log viewer](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/logs/%2Bpage.svelte): `frontend/src/routes/logs/+page.svelte`
- [Settings](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/routes/settings/%2Bpage.svelte): `frontend/src/routes/settings/+page.svelte`
- [Localization](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/stores/locale.ts): `frontend/src/lib/stores/locale.ts`
- [PocketBase client](https://github.com/seriousm4x/upsnap/blob/master/frontend/src/lib/stores/pocketbase.ts): `frontend/src/lib/stores/pocketbase.ts`

### PocketBase application

- [Application entry](https://github.com/seriousm4x/upsnap/blob/master/backend/main.go): `backend/main.go`
- [PocketBase setup](https://github.com/seriousm4x/upsnap/blob/master/backend/pb/pb.go): `backend/pb/pb.go`
- [Device handlers](https://github.com/seriousm4x/upsnap/blob/master/backend/pb/handlers.go): `backend/pb/handlers.go`
- [Scan handler](https://github.com/seriousm4x/upsnap/blob/master/backend/pb/handlerscan_linux.go): `backend/pb/handlerscan_linux.go`
- [Authorization middleware](https://github.com/seriousm4x/upsnap/blob/master/backend/pb/middlewares.go): `backend/pb/middlewares.go`
- **PocketBase records**

### Network operations

- [Wake packets](https://github.com/seriousm4x/upsnap/blob/master/backend/networking/magicpacket.go): `backend/networking/magicpacket.go`
- [Device control](https://github.com/seriousm4x/upsnap/blob/master/backend/networking/wake.go): `backend/networking/wake.go`
- [Shutdown commands](https://github.com/seriousm4x/upsnap/blob/master/backend/networking/shutdown.go): `backend/networking/shutdown.go`
- [Reachability checks](https://github.com/seriousm4x/upsnap/blob/master/backend/networking/ping.go): `backend/networking/ping.go`
- [Network discovery](https://github.com/seriousm4x/upsnap/blob/master/backend/networking/scan.go): `backend/networking/scan.go`
- [IP tracking](https://github.com/seriousm4x/upsnap/blob/master/backend/iptracking/iptracking.go): `backend/iptracking/iptracking.go`

### Automation

- [Scheduled jobs](https://github.com/seriousm4x/upsnap/blob/master/backend/cronjobs/cronjobs.go): `backend/cronjobs/cronjobs.go`
- [Logging](https://github.com/seriousm4x/upsnap/blob/master/backend/logging/logging.go): `backend/logging/logging.go`

### Other components

- **User**
- **Nmap**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → PocketBase client: loads auth and settings (evidence: `frontend/src/routes/+layout.svelte`)
- App shell → Device dashboard: renders routes
- Device dashboard → PocketBase client: subscribes to records (evidence: `frontend/src/routes/+page.svelte`)
- Device management → PocketBase client: saves devices (evidence: `frontend/src/lib/components/DeviceForm.svelte`)
- User → Device management: configures devices
- User → Scan interface: discovers devices (evidence: `README.md`)
- User → Account management: manages account (evidence: `README.md`)
- User → Admin pages: administers users (evidence: `README.md`)
- User → Log viewer: reviews logs (evidence: `README.md`)
- User → Settings: configures app (evidence: `README.md`)
- App shell → Localization: sets locale (evidence: `frontend/src/routes/+layout.svelte`)
- Application entry → PocketBase setup: starts (evidence: `backend/main.go`)
- PocketBase setup → Device handlers: registers routes
- PocketBase setup → Authorization middleware: configures authorization
- PocketBase setup → PocketBase records: uses records
- Device handlers → PocketBase records: reads and saves (evidence: `backend/pb/handlers.go`)
- Device handlers → Device control: controls devices (evidence: `backend/pb/handlers.go`)
- Device control → Wake packets: sends wake packet (evidence: `backend/networking/magicpacket.go`)
- Device handlers → Shutdown commands: requests shutdown (evidence: `README.md`)
- Scan handler → PocketBase records: reads scan settings (evidence: `backend/pb/handlerscan_linux.go`)
- Scan handler → Nmap: runs scan (evidence: `backend/pb/handlerscan_linux.go`)
- Scan interface → PocketBase client: requests scan
- PocketBase client → Application entry: calls PocketBase API
- Scheduled jobs → PocketBase records: reads and updates devices (evidence: `backend/cronjobs/cronjobs.go`)
- Scheduled jobs → Reachability checks: checks status (evidence: `backend/cronjobs/cronjobs.go`)
- Scheduled jobs → IP tracking: schedules sweeps (evidence: `backend/cronjobs/cronjobs.go`)
- Scheduled jobs → Device control: runs timed actions (evidence: `README.md`)
- IP tracking → Nmap: scans subnets (evidence: `README.md`)
- Log viewer → PocketBase client: fetches logs (evidence: `frontend/src/routes/logs/+page.svelte`)
- Device handlers → Logging: records events
