# rwilliamspbg-ops/sovereign-mohawk-proto architecture

> Architecture diagram of the GitHub repository rwilliamspbg-ops/sovereign-mohawk-proto, 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/rwilliamspbg-ops/sovereign-mohawk-proto
- Repository: https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto
- Video tour (about a minute): https://gitdiagram.com/rwilliamspbg-ops/sovereign-mohawk-proto/video

## Overview

Sovereign Mohawk Proto is a federated-learning runtime, with a Python/Flower adoption path and a separate operations-assistant UI. The principal documented flow is SDK client → runtime update exchange → federated processing; the sampled node agent and orchestrator show job delivery, gradient transport, and checkpoint access. The graph also preserves documented federation, privacy, attestation, and observability capabilities. Several subsystems are represented at their exact enclosing directories because their implementation files were not sampled; edges are limited to shown calls or README statements.

Main entry points: [`cmd/node-agent/main.go`](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/node-agent/main.go) (Node agent), [`cmd/orchestrator/main.go`](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/orchestrator/main.go) (Orchestrator), [`web/ops-assistant/client/App.tsx`](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/App.tsx) (Assistant application), [`sdk/python/mohawk/client.py`](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/sdk/python/mohawk/client.py) (Python SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SDK and workflow"]
  node_python_sdk["Python SDK<br/>[client.py]"]
  node_flower["Flower integration<br/>[flower_client.py]"]
end

subgraph group_runtime["Runtime coordination"]
  node_node_agent["Node agent<br/>[main.go]"]
  node_orchestrator["Orchestrator<br/>[main.go]"]
  node_orchestrator_server["Runtime API<br/>[server.go]"]
  node_wasm_host["WASM task host<br/>[host.go]"]
  node_manifest["Task manifest<br/>[manifest.go]"]
  node_p2p_network["P2P gradient transport<br/>[gradient.go]"]
  node_checkpoint_store[("Checkpoint storage<br/>[backend.go]")]
end

subgraph group_federation["Federated processing"]
  node_federation_rpc["Federation RPC<br/>[rpc_handler.go]"]
  node_aggregation["Gradient aggregation<br/>[aggregator.go]"]
  node_stream_aggregation["Streaming aggregation"]
  node_routing["Insight routing<br/>[router.go]"]
end

subgraph group_trust["Trust and privacy"]
  node_rdp_privacy["RDP accounting<br/>[rdp_accountant.go]"]
  node_tpm["TPM attestation<br/>[tpm.go]"]
  node_proofs["Proof verification<br/>[verifier.go]"]
end

subgraph group_ops["Operations assistant"]
  node_metrics["Runtime metrics<br/>[metrics.go]"]
  node_ops_app["Assistant application<br/>[App.tsx]"]
  node_metrics_view["Metrics view<br/>[MetricsView.tsx]"]
  node_grafana_view["Grafana dashboards"]
  node_a2ui["Action renderer<br/>[A2UIRenderer.tsx]"]
  node_api_config["API URL config<br/>[config.ts]"]
end

node_developer(("FL developer"))

node_developer -->|"uses"| node_python_sdk
node_python_sdk -->|"supports"| node_flower
node_python_sdk -.->|"exchanges updates"| node_node_agent
node_node_agent -->|"submits gradients"| node_orchestrator
node_orchestrator -->|"configures"| node_orchestrator_server
node_orchestrator -->|"signs manifests"| node_manifest
node_orchestrator -->|"configures"| node_checkpoint_store
node_node_agent -->|"runs tasks"| node_wasm_host
node_node_agent -->|"sends gradients"| node_p2p_network
node_orchestrator -->|"registers handler"| node_p2p_network
node_orchestrator_server -->|"reads checkpoints"| node_checkpoint_store
node_orchestrator_server -->|"records denials"| node_metrics
node_node_agent -->|"records metrics"| node_metrics
node_ops_app -->|"builds API URLs"| node_api_config
node_ops_app -->|"renders"| node_metrics_view
node_ops_app -->|"renders"| node_grafana_view
node_ops_app -->|"renders"| node_a2ui
node_metrics_view -->|"builds API URLs"| node_api_config
node_grafana_view -->|"builds API URLs"| node_api_config
node_federation_rpc -.->|"coordinates"| node_aggregation
node_aggregation -.->|"accounts privacy"| node_rdp_privacy
node_node_agent -->|"attests node"| node_tpm
node_node_agent -->|"verifies proof"| node_proofs
node_developer -.->|"shares insights"| node_routing

click node_python_sdk "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/sdk/python/mohawk/client.py"
click node_flower "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/sdk/python/mohawk/flower_client.py"
click node_node_agent "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/node-agent/main.go"
click node_orchestrator "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/orchestrator/main.go"
click node_orchestrator_server "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/orchestrator/server.go"
click node_wasm_host "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/wasmhost/host.go"
click node_manifest "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/manifest/manifest.go"
click node_p2p_network "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/network/gradient.go"
click node_checkpoint_store "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/ipfs/backend.go"
click node_federation_rpc "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/federation/rpc_handler.go"
click node_aggregation "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/aggregator.go"
click node_stream_aggregation "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/streaming_aggregator.go"
click node_routing "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/router/router.go"
click node_rdp_privacy "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/rdp_accountant.go"
click node_tpm "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/tpm/tpm.go"
click node_proofs "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/proofs/verifier.go"
click node_metrics "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/metrics/metrics.go"
click node_ops_app "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/App.tsx"
click node_metrics_view "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/components/MetricsView.tsx"
click node_grafana_view "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/components/GrafanaDashboardView.tsx"
click node_a2ui "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/components/A2UIRenderer.tsx"
click node_api_config "https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/config.ts"

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_python_sdk,node_flower toneBlue
class node_node_agent,node_orchestrator,node_orchestrator_server,node_wasm_host,node_manifest,node_p2p_network,node_checkpoint_store toneAmber
class node_federation_rpc,node_aggregation,node_stream_aggregation,node_routing toneMint
class node_rdp_privacy,node_tpm,node_proofs toneRose
class node_metrics,node_ops_app,node_metrics_view,node_grafana_view,node_a2ui,node_api_config,node_developer toneIndigo
```

## Components

### SDK and workflow

- [Python SDK](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/sdk/python/mohawk/client.py): `sdk/python/mohawk/client.py`
- [Flower integration](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/sdk/python/mohawk/flower_client.py): `sdk/python/mohawk/flower_client.py`

### Runtime coordination

- [Node agent](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/node-agent/main.go): `cmd/node-agent/main.go`
- [Orchestrator](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/orchestrator/main.go): `cmd/orchestrator/main.go`
- [Runtime API](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/cmd/orchestrator/server.go): `cmd/orchestrator/server.go`
- [WASM task host](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/wasmhost/host.go): `internal/wasmhost/host.go`
- [Task manifest](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/manifest/manifest.go): `internal/manifest/manifest.go`
- [P2P gradient transport](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/network/gradient.go): `internal/network/gradient.go`
- [Checkpoint storage](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/ipfs/backend.go): `internal/ipfs/backend.go`

### Federated processing

- [Federation RPC](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/federation/rpc_handler.go): `internal/federation/rpc_handler.go`
- [Gradient aggregation](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/aggregator.go): `internal/aggregator.go`
- [Streaming aggregation](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/streaming_aggregator.go): `internal/streaming_aggregator.go`
- [Insight routing](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/router/router.go): `internal/router/router.go`

### Trust and privacy

- [RDP accounting](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/rdp_accountant.go): `internal/rdp_accountant.go`
- [TPM attestation](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/tpm/tpm.go): `internal/tpm/tpm.go`
- [Proof verification](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/proofs/verifier.go): `internal/proofs/verifier.go`

### Operations assistant

- [Runtime metrics](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`
- [Assistant application](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/App.tsx): `web/ops-assistant/client/App.tsx`
- [Metrics view](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/components/MetricsView.tsx): `web/ops-assistant/client/components/MetricsView.tsx`
- [Grafana dashboards](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/components/GrafanaDashboardView.tsx): `web/ops-assistant/client/components/GrafanaDashboardView.tsx`
- [Action renderer](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/components/A2UIRenderer.tsx): `web/ops-assistant/client/components/A2UIRenderer.tsx`
- [API URL config](https://github.com/rwilliamspbg-ops/sovereign-mohawk-proto/blob/main/web/ops-assistant/client/config.ts): `web/ops-assistant/client/config.ts`

### Other components

- **FL developer**

## Connections

- FL developer → Python SDK: uses (evidence: `README.md`)
- Python SDK → Flower integration: supports (evidence: `README.md`)
- Python SDK → Node agent: exchanges updates
- Node agent → Orchestrator: submits gradients (evidence: `cmd/node-agent/main.go`)
- Orchestrator → Runtime API: configures (evidence: `cmd/orchestrator/main.go`)
- Orchestrator → Task manifest: signs manifests (evidence: `cmd/orchestrator/main.go`)
- Orchestrator → Checkpoint storage: configures (evidence: `cmd/orchestrator/main.go`)
- Node agent → WASM task host: runs tasks (evidence: `cmd/node-agent/main.go`)
- Node agent → P2P gradient transport: sends gradients (evidence: `cmd/node-agent/main.go`)
- Orchestrator → P2P gradient transport: registers handler (evidence: `cmd/orchestrator/main.go`)
- Runtime API → Checkpoint storage: reads checkpoints (evidence: `cmd/orchestrator/server.go`)
- Runtime API → Runtime metrics: records denials (evidence: `cmd/orchestrator/server.go`)
- Node agent → Runtime metrics: records metrics (evidence: `cmd/node-agent/main.go`)
- Assistant application → API URL config: builds API URLs (evidence: `web/ops-assistant/client/App.tsx`)
- Assistant application → Metrics view: renders (evidence: `web/ops-assistant/client/App.tsx`)
- Assistant application → Grafana dashboards: renders (evidence: `web/ops-assistant/client/App.tsx`)
- Assistant application → Action renderer: renders (evidence: `web/ops-assistant/client/App.tsx`)
- Metrics view → API URL config: builds API URLs (evidence: `web/ops-assistant/client/components/MetricsView.tsx`)
- Grafana dashboards → API URL config: builds API URLs (evidence: `web/ops-assistant/client/components/GrafanaDashboardView.tsx`)
- Federation RPC → Gradient aggregation: coordinates
- Gradient aggregation → RDP accounting: accounts privacy
- Node agent → TPM attestation: attests node (evidence: `cmd/node-agent/main.go`)
- Node agent → Proof verification: verifies proof (evidence: `cmd/node-agent/main.go`)
- FL developer → Insight routing: shares insights