# sternnick/edge-vps architecture

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

- Interactive diagram: https://gitdiagram.com/sternnick/edge-vps
- Repository: https://github.com/sternnick/edge-vps

## Overview

edge-vps is an operational baseline for provisioning and maintaining the public Pangolin edge host; it does not configure Pangolin itself. The main operator workflow runs the numbered enrollment, shipping, preparation, SSH-staging, and proof steps, with proof serving as the in-service gate. Supporting capabilities cover host measurement, maintenance and backup tools, host-specific configuration, declared state, and operational procedures such as rebuild, networking, and engine decisions. Relationships below follow the README; sampled source was limited to the host-literal checker, so unshown script internals are not inferred.

Main entry points: [`scripts/run-all.sh`](https://github.com/sternnick/edge-vps/blob/main/scripts/run-all.sh) (Run sequence), [`docs/procedure/state-and-backup.md`](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/state-and-backup.md) (State and backup), [`scripts/05_prove.sh`](https://github.com/sternnick/edge-vps/blob/main/scripts/05_prove.sh) (Prove readiness), [`scripts/03_prep.sh`](https://github.com/sternnick/edge-vps/blob/main/scripts/03_prep.sh) (Prepare host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["Provisioning workflow"]
  node_runner["Run sequence<br/>[run-all.sh]"]
  node_enroll["Enroll key<br/>[01_enroll-key.sh]"]
  node_ship["Ship repository<br/>[02_ship.sh]"]
  node_prep["Prepare host<br/>[03_prep.sh]"]
  node_sshd["Stage SSH<br/>[04_stage-sshd.sh]"]
  node_prove["Prove readiness<br/>[05_prove.sh]"]
end

subgraph group_host["Host configuration"]
  node_hostconfig["Host identity config<br/>[edge.env.example]"]
  node_state["Declared state<br/>[README.md]"]
  node_engine["Engine choice"]
  node_accounts["Account names"]
  node_changelog["State changes<br/>[changelog.md]"]
end

subgraph group_operations["Operations and safeguards"]
  node_detect["Host detection<br/>[detect.sh]"]
  node_backup["Offsite backup<br/>[offsite-backup.sh]"]
  node_reclaim["Disk reclaim<br/>[reclaim-disk.sh]"]
  node_reboot["Safe reboot<br/>[reboot-safe.sh]"]
  node_preflight["Reboot preflight"]
  node_pq["KEX diagnosis<br/>[pq-check.sh]"]
  node_literals["Identity rule gate"]
end

subgraph group_guidance["Operational guidance"]
  node_baseline["Maintenance baseline<br/>[baseline.md]"]
  node_rebuild["Rebuild runbook<br/>[rebuild-runbook.md]"]
  node_pangolin["Public-edge implications<br/>[pangolin-on-vps.md]"]
  node_ipv6["IPv6 readiness<br/>[ipv6.md]"]
  node_backupguide["State and backup"]
  node_provider["Provider checklist"]
  node_engineguide["Engine decision"]
  node_rules["Repository rules<br/>[rules.md]"]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_runner
node_runner -->|"runs numbered steps"| node_enroll
node_runner -->|"runs numbered steps"| node_ship
node_runner -->|"runs numbered steps"| node_prep
node_runner -->|"runs numbered steps"| node_sshd
node_runner -->|"runs numbered steps"| node_prove
node_prove -->|"declares readiness"| node_operator
node_literals -->|"enforces"| node_rules
node_backupguide -.->|"documents"| node_backup
node_rebuild -->|"documents workflow"| node_runner
node_baseline -->|"describes toggles"| node_prep
node_engineguide -->|"documents decision"| node_engine
node_backupguide -->|"describes recovery"| node_state

click node_runner "https://github.com/sternnick/edge-vps/blob/main/scripts/run-all.sh"
click node_enroll "https://github.com/sternnick/edge-vps/blob/main/scripts/01_enroll-key.sh"
click node_ship "https://github.com/sternnick/edge-vps/blob/main/scripts/02_ship.sh"
click node_prep "https://github.com/sternnick/edge-vps/blob/main/scripts/03_prep.sh"
click node_sshd "https://github.com/sternnick/edge-vps/blob/main/scripts/04_stage-sshd.sh"
click node_prove "https://github.com/sternnick/edge-vps/blob/main/scripts/05_prove.sh"
click node_detect "https://github.com/sternnick/edge-vps/blob/main/scripts/lib/detect.sh"
click node_hostconfig "https://github.com/sternnick/edge-vps/blob/main/config/edge.env.example"
click node_state "https://github.com/sternnick/edge-vps/blob/main/state/README.md"
click node_engine "https://github.com/sternnick/edge-vps/blob/main/state/engine"
click node_accounts "https://github.com/sternnick/edge-vps/blob/main/state/accounts"
click node_changelog "https://github.com/sternnick/edge-vps/blob/main/state/changelog.md"
click node_backup "https://github.com/sternnick/edge-vps/blob/main/scripts/tools/offsite-backup.sh"
click node_reclaim "https://github.com/sternnick/edge-vps/blob/main/scripts/tools/reclaim-disk.sh"
click node_reboot "https://github.com/sternnick/edge-vps/blob/main/scripts/tools/reboot-safe.sh"
click node_preflight "https://github.com/sternnick/edge-vps/blob/main/scripts/tools/preflight-reboot.sh"
click node_pq "https://github.com/sternnick/edge-vps/blob/main/scripts/tools/pq-check.sh"
click node_literals "https://github.com/sternnick/edge-vps/blob/main/scripts/tools/check_host_literals.py"
click node_baseline "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/baseline.md"
click node_rebuild "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/rebuild-runbook.md"
click node_pangolin "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/pangolin-on-vps.md"
click node_ipv6 "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/ipv6.md"
click node_backupguide "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/state-and-backup.md"
click node_provider "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/provider-checklist.md"
click node_engineguide "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/docker-vs-podman.md"
click node_rules "https://github.com/sternnick/edge-vps/blob/main/docs/procedure/rules.md"

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_runner,node_enroll,node_ship,node_prep,node_sshd,node_prove toneBlue
class node_hostconfig,node_state,node_engine,node_accounts,node_changelog toneAmber
class node_detect,node_backup,node_reclaim,node_reboot,node_preflight,node_pq,node_literals toneMint
class node_baseline,node_rebuild,node_pangolin,node_ipv6,node_backupguide,node_provider,node_engineguide,node_rules toneRose
class node_operator toneIndigo
```

## Components

### Provisioning workflow

- [Run sequence](https://github.com/sternnick/edge-vps/blob/main/scripts/run-all.sh): `scripts/run-all.sh`
- [Enroll key](https://github.com/sternnick/edge-vps/blob/main/scripts/01_enroll-key.sh): `scripts/01_enroll-key.sh`
- [Ship repository](https://github.com/sternnick/edge-vps/blob/main/scripts/02_ship.sh): `scripts/02_ship.sh`
- [Prepare host](https://github.com/sternnick/edge-vps/blob/main/scripts/03_prep.sh): `scripts/03_prep.sh`
- [Stage SSH](https://github.com/sternnick/edge-vps/blob/main/scripts/04_stage-sshd.sh): `scripts/04_stage-sshd.sh`
- [Prove readiness](https://github.com/sternnick/edge-vps/blob/main/scripts/05_prove.sh): `scripts/05_prove.sh`

### Host configuration

- [Host identity config](https://github.com/sternnick/edge-vps/blob/main/config/edge.env.example): `config/edge.env.example`
- [Declared state](https://github.com/sternnick/edge-vps/blob/main/state/README.md): `state/README.md`
- [Engine choice](https://github.com/sternnick/edge-vps/blob/main/state/engine): `state/engine`
- [Account names](https://github.com/sternnick/edge-vps/blob/main/state/accounts): `state/accounts`
- [State changes](https://github.com/sternnick/edge-vps/blob/main/state/changelog.md): `state/changelog.md`

### Operations and safeguards

- [Host detection](https://github.com/sternnick/edge-vps/blob/main/scripts/lib/detect.sh): `scripts/lib/detect.sh`
- [Offsite backup](https://github.com/sternnick/edge-vps/blob/main/scripts/tools/offsite-backup.sh): `scripts/tools/offsite-backup.sh`
- [Disk reclaim](https://github.com/sternnick/edge-vps/blob/main/scripts/tools/reclaim-disk.sh): `scripts/tools/reclaim-disk.sh`
- [Safe reboot](https://github.com/sternnick/edge-vps/blob/main/scripts/tools/reboot-safe.sh): `scripts/tools/reboot-safe.sh`
- [Reboot preflight](https://github.com/sternnick/edge-vps/blob/main/scripts/tools/preflight-reboot.sh): `scripts/tools/preflight-reboot.sh`
- [KEX diagnosis](https://github.com/sternnick/edge-vps/blob/main/scripts/tools/pq-check.sh): `scripts/tools/pq-check.sh`
- [Identity rule gate](https://github.com/sternnick/edge-vps/blob/main/scripts/tools/check_host_literals.py): `scripts/tools/check_host_literals.py`

### Operational guidance

- [Maintenance baseline](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/baseline.md): `docs/procedure/baseline.md`
- [Rebuild runbook](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/rebuild-runbook.md): `docs/procedure/rebuild-runbook.md`
- [Public-edge implications](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/pangolin-on-vps.md): `docs/procedure/pangolin-on-vps.md`
- [IPv6 readiness](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/ipv6.md): `docs/procedure/ipv6.md`
- [State and backup](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/state-and-backup.md): `docs/procedure/state-and-backup.md`
- [Provider checklist](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/provider-checklist.md): `docs/procedure/provider-checklist.md`
- [Engine decision](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/docker-vs-podman.md): `docs/procedure/docker-vs-podman.md`
- [Repository rules](https://github.com/sternnick/edge-vps/blob/main/docs/procedure/rules.md): `docs/procedure/rules.md`

### Other components

- **Operator**

## Connections

- Operator → Run sequence: starts (evidence: `README.md`)
- Run sequence → Enroll key: runs numbered steps (evidence: `README.md`)
- Run sequence → Ship repository: runs numbered steps (evidence: `README.md`)
- Run sequence → Prepare host: runs numbered steps (evidence: `README.md`)
- Run sequence → Stage SSH: runs numbered steps (evidence: `README.md`)
- Run sequence → Prove readiness: runs numbered steps (evidence: `README.md`)
- Prove readiness → Operator: declares readiness (evidence: `README.md`)
- Identity rule gate → Repository rules: enforces (evidence: `scripts/tools/check_host_literals.py`)
- State and backup → Offsite backup: documents
- Rebuild runbook → Run sequence: documents workflow (evidence: `README.md`)
- Maintenance baseline → Prepare host: describes toggles (evidence: `README.md`)
- Engine decision → Engine choice: documents decision (evidence: `README.md`)
- State and backup → Declared state: describes recovery (evidence: `README.md`)