sankofa-hw-infra/docs/sovereign-controller-topology.md

Sovereign controller topology

Per-sovereign UniFi controller domains, regionally isolated management planes, and a central read-only oversight layer. No cross-sovereign write authority.

Diagram

flowchart TB
  subgraph sovereignA [Sovereign A]
    CtrlA[UniFi Controller A]
    CtrlA -->|write| NetA[Network A]
  end

  subgraph sovereignB [Sovereign B]
    CtrlB[UniFi Controller B]
    CtrlB -->|write| NetB[Network B]
  end

  subgraph oversight [Central oversight]
    Phoenix[Sankofa Phoenix]
  end

  Phoenix -->|read only| CtrlA
  Phoenix -->|read only| CtrlB
  CtrlA -.->|no write| CtrlB
  CtrlB -.->|no write| CtrlA

Architecture

• Per-sovereign controller domains: Each sovereign (org/tenant) has its own UniFi controller(s). Write authority stays within that sovereign.
• Regional isolation: Controllers and management planes can be deployed per region so data and control stay in-region.
• Central read-only oversight: Sankofa Phoenix has a read-only view across controllers for audit, BOM, support-risk, and compliance—no write into any sovereign’s controller.
• Trust boundaries: No cross-sovereign write; sovereign A cannot change sovereign B’s network or config.

This satisfies sovereignty, auditability, compartmentalization, and trust boundaries between different bodies (e.g. governmental).

Optional: controller registry

If you store controller endpoints in the DB, use a table unifi_controllers with: org_id, site_id (optional), base_url, role (sovereign_write | oversight_read_only), region. Credentials remain in Vault; the table only stores topology and role. API: CRUD for controllers scoped by org_id.

See integration-spec-unifi.md for the “Sovereign-safe controller architecture” subsection.