# nodealchemy/powernode-system architecture

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

## Overview

Powernode System Extension supplies the substrate beneath the Powernode control plane: operators manage nodes and infrastructure, while the Go agent boots and reconciles those nodes into a governed fleet. The principal path runs from operator actions through the React surface and Rails APIs to platform-managed tasks and on-node execution; storage migration spans planning/approval and agent-side data movement. The README also documents module supply-chain, SD-WAN, fleet autonomy, and observability branches. Some subsystem links are documented capabilities rather than inspected call sites; those use README evidence.

Main entry points: [`agent/internal/runtime`](https://github.com/nodealchemy/powernode-system/tree/develop/agent/internal/runtime) (Agent Runtime), [`agent/cmd/powernode-agent`](https://github.com/nodealchemy/powernode-system/tree/develop/agent/cmd/powernode-agent) (Powernode Agent), [`frontend/src/features/system/components`](https://github.com/nodealchemy/powernode-system/tree/develop/frontend/src/features/system/components) (System UI), [`frontend/src/features/system/components/platform/StorageMigrationsPanel.tsx`](https://github.com/nodealchemy/powernode-system/blob/develop/frontend/src/features/system/components/platform/StorageMigrationsPanel.tsx) (Migration Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Operator Surface"]
  node_system_ui["System UI"]
  node_migration_panel["Migration Panel"]
  node_migration_api["Migration API Client"]
end

subgraph group_control["Control Plane"]
  node_rails["Rails Extension"]
  node_storage_api["Storage Migration API"]
  node_storage_model[("Storage Migration State")]
  node_workers["Scheduled Workers"]
  node_module_supply["Module Supply Chain"]
end

subgraph group_node["Node Runtime"]
  node_agent["Powernode Agent"]
  node_agent_runtime["Agent Runtime"]
  node_storage_tasks["Storage Task Handler<br/>[storage.go]"]
  node_storage_engine["Storage Operations"]
  node_mounts["Volume Mounting"]
  node_boot_artifacts["Boot Artifacts"]
end

subgraph group_fleet["Fleet Services"]
  node_sdwan["SD-WAN Manager<br/>[manager.go]"]
  node_fleet_autonomy["Fleet Autonomy"]
  node_fleet_events[("Fleet Events")]
end

node_operator(("Operator"))
node_platform["Powernode Platform"]
node_oci["OCI Registry"]

node_operator -->|"manages fleet"| node_system_ui
node_system_ui -.->|"opens migrations"| node_migration_panel
node_migration_panel -->|"requests actions"| node_migration_api
node_migration_api -->|"calls endpoints"| node_storage_api
node_storage_api -.->|"manages state"| node_storage_model
node_platform -->|"hosts extension"| node_rails
node_rails -->|"schedules jobs"| node_workers
node_platform -->|"runs nodes"| node_agent
node_agent -->|"starts runtime"| node_agent_runtime
node_agent_runtime -->|"dispatches tasks"| node_storage_tasks
node_storage_tasks -->|"applies operations"| node_storage_engine
node_agent_runtime -->|"reconciles volumes"| node_mounts
node_platform -->|"publishes modules"| node_module_supply
node_module_supply -->|"stores artifacts"| node_oci
node_agent_runtime -->|"pulls modules"| node_oci
node_boot_artifacts -->|"boots agent"| node_agent
node_agent -->|"configures networking"| node_sdwan
node_workers -.->|"reconciles fleet"| node_fleet_autonomy
node_fleet_autonomy -->|"records decisions"| node_fleet_events
node_fleet_events -->|"broadcasts updates"| node_system_ui

click node_system_ui "https://github.com/nodealchemy/powernode-system/tree/develop/frontend/src/features/system/components"
click node_migration_panel "https://github.com/nodealchemy/powernode-system/blob/develop/frontend/src/features/system/components/platform/StorageMigrationsPanel.tsx"
click node_migration_api "https://github.com/nodealchemy/powernode-system/blob/develop/frontend/src/features/system/services/api/storageMigrationsApi.ts"
click node_rails "https://github.com/nodealchemy/powernode-system/tree/develop/server/app"
click node_storage_api "https://github.com/nodealchemy/powernode-system/blob/develop/server/app/controllers/api/v1/system/platform/storage_migrations_controller.rb"
click node_storage_model "https://github.com/nodealchemy/powernode-system/blob/develop/server/app/models/system/storage_migration.rb"
click node_workers "https://github.com/nodealchemy/powernode-system/tree/develop/worker/app/jobs"
click node_agent "https://github.com/nodealchemy/powernode-system/tree/develop/agent/cmd/powernode-agent"
click node_agent_runtime "https://github.com/nodealchemy/powernode-system/tree/develop/agent/internal/runtime"
click node_storage_tasks "https://github.com/nodealchemy/powernode-system/blob/develop/agent/internal/runtime/tasks/handlers/storage.go"
click node_storage_engine "https://github.com/nodealchemy/powernode-system/tree/develop/agent/internal/storage"
click node_mounts "https://github.com/nodealchemy/powernode-system/tree/develop/agent/internal/mount"
click node_module_supply "https://github.com/nodealchemy/powernode-system/blob/develop/server/app/services/system/module_oci_ingest_service.rb"
click node_boot_artifacts "https://github.com/nodealchemy/powernode-system/tree/develop/initramfs"
click node_sdwan "https://github.com/nodealchemy/powernode-system/blob/develop/agent/internal/sdwan/manager.go"
click node_fleet_autonomy "https://github.com/nodealchemy/powernode-system/tree/develop/server/app/services/system/fleet"
click node_fleet_events "https://github.com/nodealchemy/powernode-system/tree/develop/server/app/models/system"

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_system_ui,node_migration_panel,node_migration_api toneBlue
class node_rails,node_storage_api,node_storage_model,node_workers,node_module_supply toneAmber
class node_agent,node_agent_runtime,node_storage_tasks,node_storage_engine,node_mounts,node_boot_artifacts toneMint
class node_sdwan,node_fleet_autonomy,node_fleet_events toneRose
class node_operator,node_platform,node_oci toneIndigo
```

## Components

### Operator Surface

- [System UI](https://github.com/nodealchemy/powernode-system/tree/develop/frontend/src/features/system/components): `frontend/src/features/system/components`
- [Migration Panel](https://github.com/nodealchemy/powernode-system/blob/develop/frontend/src/features/system/components/platform/StorageMigrationsPanel.tsx): `frontend/src/features/system/components/platform/StorageMigrationsPanel.tsx`
- [Migration API Client](https://github.com/nodealchemy/powernode-system/blob/develop/frontend/src/features/system/services/api/storageMigrationsApi.ts): `frontend/src/features/system/services/api/storageMigrationsApi.ts`

### Control Plane

- [Rails Extension](https://github.com/nodealchemy/powernode-system/tree/develop/server/app): `server/app`
- [Storage Migration API](https://github.com/nodealchemy/powernode-system/blob/develop/server/app/controllers/api/v1/system/platform/storage_migrations_controller.rb): `server/app/controllers/api/v1/system/platform/storage_migrations_controller.rb`
- [Storage Migration State](https://github.com/nodealchemy/powernode-system/blob/develop/server/app/models/system/storage_migration.rb): `server/app/models/system/storage_migration.rb`
- [Scheduled Workers](https://github.com/nodealchemy/powernode-system/tree/develop/worker/app/jobs): `worker/app/jobs`
- [Module Supply Chain](https://github.com/nodealchemy/powernode-system/blob/develop/server/app/services/system/module_oci_ingest_service.rb): `server/app/services/system/module_oci_ingest_service.rb`

### Node Runtime

- [Powernode Agent](https://github.com/nodealchemy/powernode-system/tree/develop/agent/cmd/powernode-agent): `agent/cmd/powernode-agent`
- [Agent Runtime](https://github.com/nodealchemy/powernode-system/tree/develop/agent/internal/runtime): `agent/internal/runtime`
- [Storage Task Handler](https://github.com/nodealchemy/powernode-system/blob/develop/agent/internal/runtime/tasks/handlers/storage.go): `agent/internal/runtime/tasks/handlers/storage.go`
- [Storage Operations](https://github.com/nodealchemy/powernode-system/tree/develop/agent/internal/storage): `agent/internal/storage`
- [Volume Mounting](https://github.com/nodealchemy/powernode-system/tree/develop/agent/internal/mount): `agent/internal/mount`
- [Boot Artifacts](https://github.com/nodealchemy/powernode-system/tree/develop/initramfs): `initramfs`

### Fleet Services

- [SD-WAN Manager](https://github.com/nodealchemy/powernode-system/blob/develop/agent/internal/sdwan/manager.go): `agent/internal/sdwan/manager.go`
- [Fleet Autonomy](https://github.com/nodealchemy/powernode-system/tree/develop/server/app/services/system/fleet): `server/app/services/system/fleet`
- [Fleet Events](https://github.com/nodealchemy/powernode-system/tree/develop/server/app/models/system): `server/app/models/system`

### Other components

- **Operator**
- **Powernode Platform**
- **OCI Registry**

## Connections

- Operator → System UI: manages fleet
- System UI → Migration Panel: opens migrations (evidence: `frontend/src/features/system/components/platform/StorageMigrationsPanel.tsx`)
- Migration Panel → Migration API Client: requests actions (evidence: `frontend/src/features/system/components/platform/StorageMigrationsPanel.tsx`)
- Migration API Client → Storage Migration API: calls endpoints (evidence: `frontend/src/features/system/services/api/storageMigrationsApi.ts`)
- Storage Migration API → Storage Migration State: manages state
- Powernode Platform → Rails Extension: hosts extension
- Rails Extension → Scheduled Workers: schedules jobs
- Powernode Platform → Powernode Agent: runs nodes
- Powernode Agent → Agent Runtime: starts runtime
- Agent Runtime → Storage Task Handler: dispatches tasks (evidence: `agent/internal/runtime/tasks/handlers/storage.go`)
- Storage Task Handler → Storage Operations: applies operations (evidence: `agent/internal/runtime/tasks/handlers/storage.go`)
- Agent Runtime → Volume Mounting: reconciles volumes (evidence: `agent/internal/runtime/storage_volume_client.go`)
- Powernode Platform → Module Supply Chain: publishes modules
- Module Supply Chain → OCI Registry: stores artifacts
- Agent Runtime → OCI Registry: pulls modules
- Boot Artifacts → Powernode Agent: boots agent
- Powernode Agent → SD-WAN Manager: configures networking
- Scheduled Workers → Fleet Autonomy: reconciles fleet
- Fleet Autonomy → Fleet Events: records decisions
- Fleet Events → System UI: broadcasts updates
