proxmox/docs/02-architecture/ARCHITECTURAL_INTENT.md

Architectural Intent — Sankofa Phoenix

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Last reviewed: 2026-01-20
Status: Intent Document (Not Enforcement Contract)

---

Purpose of This Document

This document describes intended architectural roles and boundaries for Sankofa Phoenix services. It is an intent statement, not a permanent contract. Implementations may evolve without violating these intents.

Key Principle: Intent ≠ Contract. Evolution is expected and encouraged.

---

Core Architectural Intents

1. Phoenix Cloud Platform

Intended Role: Sovereign-grade cloud infrastructure control plane

Intended Characteristics:

• Operator-facing control plane
• API-first architecture
• Multi-tenant resource provisioning
• Service orchestration and lifecycle management

Current Implementation:

• GraphQL API at phoenix.sankofa.nexus
• VMID 7800, 192.168.11.50:4000

Intent Flexibility:

"Phoenix is intended to operate as an operator-facing control plane. This does not preclude future public or delegated interfaces."

What This Means:

• Current: API-first, operator-facing
• Future: May evolve to include public UI, delegated access, or other interfaces
• No permanent restriction on access patterns

---

2. Sankofa Brand & Access Layer

Intended Role: Corporate presence and brand narrative

Intended Characteristics:

• Public-facing corporate website
• Brand philosophy and mission
• Entry point to Phoenix services
• Sovereign identity messaging

Current Implementation:

• Next.js portal at sankofa.nexus
• VMID 7801, 192.168.11.51:3000
• Currently presents login-gated interface

Intent Flexibility:

"Sankofa Portal serves as the corporate brand surface. Authentication requirements are policy-driven and may evolve."

What This Means:

• Current: Login-gated interface
• Future: May split into public marketing + authenticated portal, or maintain unified model
• Auth is a policy boundary, not a permanent architectural constraint

---

3. Public Transparency Layer (Explorer)

Intended Role: Public blockchain transparency and settlement inspection

Intended Characteristics:

• Public access (no authentication required)
• ChainID 138 block explorer
• Transaction and address inspection
• Network metrics and statistics

Current Implementation:

• SolaceScanScout at explorer.d-bis.org
• VMID 5000, 192.168.11.140
• Blockscout-based technology

Intent Flexibility:

"The explorer serves as public infrastructure for ChainID 138. It remains independent from portal authentication systems."

What This Means:

• Current: Public, no auth, separate from Phoenix/Sankofa
• Future: May evolve branding, federation, or additional features
• Independence from portal auth is intentional, not permanent

---

Service Boundary Intentions

Brand Surface vs Control Surface

Intent: Clear separation in language and documentation, not necessarily in code or infrastructure.

Brand Surface:

• Corporate presence
• Public messaging
• Product introduction

Control Surface:

• Infrastructure management
• Resource provisioning
• Operational controls

Flexibility:

• These are descriptive roles, not structural mandates
• Implementation may evolve
• No requirement for separate repos, DNS structures, or service meshes

---

Canonical vs Non-Canonical Services

Intent: Use canonical/non-canonical labels to clarify without restricting.

Canonical Services:

• sankofa.nexus — Canonical corporate website
• phoenix.sankofa.nexus — Canonical cloud control plane
• explorer.d-bis.org — Canonical ChainID 138 explorer

Non-Canonical Services:

• blockscout.defi-oracle.io — Reference/experimental instance

Flexibility:

• Canonical status can change
• Non-canonical can be promoted
• No implied permanence

---

Policy Boundaries (Not Feature Boundaries)

Authentication Requirements

Intent: Document auth as policy, not permanent feature.

Current Policy:

• Phoenix: Operator authentication required
• Sankofa Portal: Currently requires authentication
• Explorer: No authentication required

Flexibility:

• Auth requirements are policy-driven
• Can be adjusted based on governance decisions
• Not a permanent architectural constraint

---

Naming and Identity Intentions

Intent: Use names that describe role, not implementation.

Examples:

• "Phoenix Cloud Services" — Describes role
• "SolaceScanScout" — Describes purpose
• "ChainID 138 Explorer" — Describes function

Avoid:

• Names that imply finality
• Names that encode technology choices
• Names that imply jurisdictional permanence

---

Evolution Pathways (Non-Binding)

These are possible futures, not commitments:

Possible Future Evolutions

1. Public Marketing Split

   • www.sankofa.nexus → Public marketing
   • portal.sankofa.nexus → Authenticated portal
   • Or maintain unified model

2. Phoenix UI Evolution

   • May develop delegated UI interfaces
   • May expose public-facing features
   • Remains API-first, but UI is not precluded

3. Explorer Branding

   • May align branding with DBIS Core products
   • May federate with other explorers
   • May evolve independently

Note: These are illustrative possibilities, not requirements or commitments.

---

What This Document Does NOT Do

This document does not:

• ❌ Lock repo structure to domains
• ❌ Mandate folder structures
• ❌ Require service mesh topology
• ❌ Enforce immutable governance rules
• ❌ Create "security by DNS" decisions
• ❌ Force marketing vs ops separation
• ❌ Map to specific compliance frameworks

Why: These would create permanent constraints. This document preserves optionality.

---

Review and Evolution

Review Cadence: As needed, when architectural decisions are made

Evolution Process:

• Intent can be refined based on experience
• Implementations can evolve independently
• No requirement to update this document for every implementation change

Authority: This document reflects architectural intent, not implementation contracts.

---

Last Updated: 2026-01-20
Status: Intent Document (Flexible, Non-Constraining)