Sankofa/docs/phoenix/UPDATED_PLAN.md

Phoenix Operating Model Documentation - Updated Plan

Overview

This is the updated plan for creating comprehensive documentation for Phoenix (Sankofa Cloud Services) operating model, addressing all identified gaps and inconsistencies from the review.

Critical Context:

• Sankofa and Phoenix serve international and multi-national Sovereign Governments
• This requires clouds for sovereignty and multi-region landing zones
• Both the customers (sovereign governments) and Sankofa/Phoenix itself operate in a decentralized nature
• Documentation must assist in understanding all capabilities and this decentralized architecture

---

Key Changes from Original Plan

1. Resolved Entity Model Inconsistencies

• Clarified Client (Billing Profile) vs Tenant relationship
• Documented migration path from existing tenant-based model
• Aligned billing model with Client/Tenant separation
• Aligned identity model with Tenant entity

2. Expanded Content & DevOps Plane

• Detailed enterprise content hierarchy
• Git structure and governance
• CI/CD integration patterns
• Promotion flow implementation
• Integration with existing ArgoCD

3. Added Missing Sections

• Key Rules and Constraints section
• Integration Mapping section
• Glossary section
• Migration Guide
• Detailed entity schemas

4. Enhanced Multi-Region & Decentralized Coverage

• Landing zone implementation details
• Decentralized architecture patterns
• Multi-national government scenarios
• Cross-region governance mechanisms

---

Deliverables

1. Core Operating Model Document

File: docs/phoenix/OPERATING_MODEL.md

Sections:

1. Executive Summary

   • Purpose and scope
   • Target audience (international/multi-national sovereign governments)
   • Competitive positioning

2. Core Management Layers (Separation of Concerns)

   • Five control planes overview
   • Orthogonal but linked design
   • ID-based references

3. Commercial Plane — Clients (Billing Profiles)

   • Entity: Client (Billing Profile)
   • Attributes:
     • Legal Entity
     • Contract & MSA
     • Invoicing configuration
     • Payment instruments
     • Cost centers / departments
     • Usage aggregation & chargeback
   • Key Rules:
     • A Client can own multiple Tenants
     • A Tenant cannot span multiple Clients
     • Billing is never tied directly to environments or repos
   • Relationship to existing billing system
   • Multi-national client structures

4. Tenancy Plane — Tenants (Domains)

   • Entity: Tenant
   • Attributes:
     • Primary domain(s)
     • Identity provider (SSO, Entra, Okta, etc.)
     • Global RBAC namespace
     • Data residency / sovereignty flags
     • Compliance profile (ISO, SOC, HIPAA, etc.)
     • Multi-region support
     • Regional data residency requirements
     • Cross-border governance settings
   • Key Rules:
     • One Tenant → many Subscriptions
     • One Tenant → many Environments
     • Tenant is the security blast-radius boundary
   • Relationship to existing tenant management
   • Keycloak realm mapping
   • Multi-national tenant structures

5. Subscription Plane — Subscriptions

   • Entity: Subscription
   • Attributes:
     • Service bundles (compute, data, AI, storage, etc.)
     • Quotas & limits
     • Cost tracking
     • Policy packs (security, networking, data access)
     • Feature entitlements
     • Multi-region subscriptions
   • Key Rules:
     • Subscriptions live inside a Tenant
     • Subscriptions are mapped to one Client billing profile
   • Subscription Types:
     • Shared Platform Subscription
     • Product Subscriptions
     • Sandbox / Innovation Subscriptions
   • Multi-region subscription patterns

6. Environment Plane — Environments

   • Entity: Environment
   • Attributes:
     • Network isolation
     • Data isolation
     • Deployment policies
     • Runtime secrets
     • Compliance overlays
     • Regional scope
   • Key Rules:
     • Environments belong to Subscriptions
     • Promotion flows are policy-driven, not manual
     • PROD access is always the most restricted
   • Environment Types:
     • DEV
     • INT
     • UAT
     • STAGING
     • PROD
     • REGULATED (optional)
     • SOVEREIGN (optional)
     • AIR-GAPPED (optional)
   • Multi-region environment patterns

7. Content & DevOps Plane (Separate but Integrated)

   • Enterprise Content Management Hierarchy:

     • Entity Model:
       • Enterprise
       • Portfolio
       • Product / Program
       • Application / Service
       • Component / Module
     • Content Types:
       • Source code
       • IaC (Terraform, Pulumi, Bicep)
       • Pipelines
       • Configuration templates
       • Documentation
       • Data schemas
       • AI models / prompts
     • Governance:
       • Ownership at each level
       • Approval workflows
       • Compliance tagging
       • Versioning & lineage

   • Git & DevOps Integration Model:

     • Git Structure:
       • Enterprise Git Org
       • Repos mapped to Product / Service
       • Branch strategy enforced by policy
       • Protected branches for regulated envs
       • Multi-region Git repository patterns
     • CI/CD:
       • Pipelines are environment-aware
       • Deployments require:
         • Subscription authorization
         • Environment approval
         • Policy validation
       • GitOps for infra & platform services
       • Integration with existing ArgoCD infrastructure
     • Promotion Flow:
       • Code Commit → CI (Test, Scan) → Artifact Registry → Environment Promotion → Subscription Deployment
       • Policy-driven promotion (not manual)
       • Critical Principle: Git never directly deploys to PROD without environment + subscription authorization
       • Multi-region promotion patterns

8. Hierarchical Access Model (RBAC)

   • Commercial Access:
     • Finance Admin
     • Billing Viewer
     • Cost Center Owner
   • Tenant Access:
     • Tenant Owner
     • Security Admin
     • Identity Admin
     • Compliance Officer
   • Subscription Access:
     • Subscription Owner
     • Platform Admin
     • Service Operator
     • Read-only Auditor
   • Environment Access:
     • Environment Owner
     • Release Manager
     • Operator
     • Observer
   • Content & DevOps Access:
     • Enterprise Architect
     • Portfolio Lead
     • Product Owner
     • Dev Lead
     • Contributor
     • Reviewer
     • Release Approver
   • Cross-Plane Access:
     • No role crosses planes by default
     • Cross-plane access requires explicit delegation
     • Delegation mechanisms
     • Multi-region RBAC patterns
     • Integration with Keycloak roles

9. Key Rules and Constraints

   • All rules explicitly stated with rationale
   • Enforcement mechanisms
   • Violation handling
   • Multi-region rule variations

10. Multi-Region and Multi-National Capabilities

    • Sovereign cloud deployments per region/nation
    • Cross-region governance
    • Multi-national tenant structures
    • Regional data residency
    • Landing zone patterns

11. Decentralized Architecture

    • How decentralization enables sovereignty
    • Distributed control planes
    • Cross-region coordination
    • Federated identity and governance
    • Eventual consistency patterns
    • Conflict resolution

12. Integration with Existing Infrastructure

    • Entity mapping to existing systems:
      • Proxmox infrastructure
      • Kubernetes clusters
      • Cloudflare tunnels and Zero Trust
      • Keycloak realms
      • ArgoCD applications
      • Crossplane resources
      • Monitoring and observability
    • Resource model mapping:
      • Region → Site → Cluster → Node
      • Tenant boundaries
      • Subscription boundaries
      • Environment boundaries
    • API integration points

13. Use Cases for Sovereign Governments

    • Multi-national defense contractor with classified workloads
    • International healthcare agency with HIPAA requirements
    • Cross-border financial regulator
    • Multi-region public sector agency
    • Air-gapped deployment per nation
    • Entity mapping for each scenario

14. Glossary

    • Definitions for all entities
    • Comparison to Azure/AWS equivalents
    • Multi-region terminology
    • Decentralized architecture terminology

2. Architecture Diagrams

File: docs/phoenix/OPERATING_MODEL_DIAGRAMS.md

Diagrams:

1. Control Plane Overview - High-level view of five planes
2. Entity Relationships - Complete graph showing Client → Tenant → Subscription → Environment → Content
3. Multi-Region Landing Zone Architecture - Sovereign clouds per region, landing zones, cross-region connectivity
4. Decentralized Control Planes - Distributed governance across regions
5. Content Hierarchy - Enterprise → Portfolio → Product → Application → Component
6. Access Model - RBAC roles across planes with regional scope
7. Promotion Flow - Code commit → CI → Artifact → Environment → Deployment (with policy gates)
8. Integration Architecture - How planes interact with existing systems
9. Sovereign Environment Isolation - REGULATED, SOVEREIGN, AIR-GAPPED environments per region
10. Multi-National Tenant Structure - How international governments are modeled
11. Landing Zone Patterns - Regional sovereign cloud deployments
12. Competitive Architecture - Phoenix vs Azure vs AWS (decentralized vs centralized)
13. Data Flow - Cross-plane operations
14. Sequence Diagram - Promotion flow with authorization gates
15. Multi-Region Topology - Network and governance topology

3. Cloud Provider Mapping & Competitive Analysis

File: docs/phoenix/CLOUD_PROVIDER_MAPPING.md

Sections:

1. Mapping to Azure

   • Azure AD Tenant → Phoenix Tenant
   • Azure Subscription → Phoenix Subscription
   • Azure Resource Groups → Phoenix Environments
   • Competitive advantages

2. Mapping to AWS

   • AWS Organizations → Phoenix Client/Tenant
   • AWS Accounts → Phoenix Subscriptions
   • AWS Regions → Phoenix Regions/Landing Zones
   • Competitive advantages

3. Hybrid Deployments

   • Sovereign + public cloud patterns
   • Integration strategies

4. Multi-Region Landing Zones

   • Azure vs AWS vs Phoenix comparison
   • Landing zone capabilities

5. Decentralized Architecture

   • How Phoenix differs from centralized Azure/AWS
   • Advantages for sovereign governments

6. Feature Comparison Matrix

   • Multi-tenancy capabilities
   • Billing granularity
   • Identity management
   • Multi-region support
   • Decentralized architecture
   • Sovereign capabilities
   • Compliance features

7. Migration Considerations

   • Migration complexity assessment
   • Data migration strategies
   • Identity migration strategies
   • Application migration strategies
   • Cost migration analysis
   • Timeline estimates
   • Step-by-step migration guides

4. Minimum Viable Control Plane

File: docs/phoenix/MVP_CONTROL_PLANE.md

Sections:

1. MVP Scope Definition

   • Which features are MVP vs future
   • Which planes are MVP vs future
   • Which integrations are MVP vs future
   • Timeline for MVP
   • Success criteria for MVP

2. MVP for Each Control Plane

   • Commercial Plane MVP
   • Tenancy Plane MVP
   • Subscription Plane MVP
   • Environment Plane MVP
   • Content & DevOps Plane MVP

3. Multi-Region MVP Requirements

   • Multi-region landing zone support
   • Cross-region governance
   • Regional data residency

4. Decentralized Architecture MVP

   • Distributed control plane deployment
   • Federated identity
   • Cross-region coordination

5. Sovereign Government MVP Requirements

   • Compliance capabilities
   • Audit capabilities
   • Air-gapped support

6. Required APIs and Services

   • API specifications per plane
   • Service dependencies
   • Integration points

7. Data Model Extensions

   • GraphQL schema extensions
   • Database schema extensions
   • Migration from existing model

8. Implementation Priorities

   • Prioritized feature list
   • Dependencies between features
   • Critical path analysis
   • Risk assessment per feature

9. Integration with Existing Infrastructure

   • MVP integration points
   • Migration path

5. Client-Facing Product Specification

File: docs/phoenix/PRODUCT_SPEC.md

Sections:

1. Executive Summary

   • Value proposition
   • Competitive advantages
   • Target market

2. Operating Model Overview

   • Five control planes
   • Key benefits
   • Use cases

3. Decentralized Architecture

   • Explanation for non-technical audience
   • Benefits for sovereign governments
   • Comparison to centralized models

4. Multi-Region Landing Zones

   • Capabilities overview
   • Use cases
   • Benefits

5. Sovereign Government Use Cases

   • Multi-national defense contractors
   • International healthcare agencies
   • Cross-border financial regulators
   • Multi-region public sector agencies
   • Air-gapped deployments per region
   • Cross-border sovereignty requirements

6. Compliance and Security Features

   • Multi-national data residency and sovereignty
   • Regional regulatory compliance (ISO, SOC, HIPAA, etc. per region)
   • Cross-border audit trails and governance
   • Air-gapped capabilities per region
   • Multi-national identity federation

7. Landing Zone Patterns

   • Patterns for sovereign governments
   • Implementation examples

8. Pricing and Packaging

   • Pricing models
   • Packaging options
   • Cost comparison to Azure/AWS

9. Migration Path

   • From Azure to Phoenix
   • From AWS to Phoenix
   • Timeline and process

10. Understanding All Capabilities

    • Complete capability matrix
    • How decentralization enables sovereignty
    • Multi-region coordination
    • Cross-border sovereignty

6. Multi-Region Landing Zones Guide

File: docs/phoenix/MULTI_REGION_LANDING_ZONES.md

Sections:

1. Landing Zone Architecture

   • Reference architecture
   • Components
   • Patterns

2. Multi-Region Deployment Patterns

   • Sovereign cloud per region/nation
   • Cross-region connectivity
   • Regional data residency
   • Multi-national coordination

3. Decentralized Governance

   • Governance across regions
   • Policy enforcement
   • Compliance per region

4. Cross-Border Sovereignty

   • Patterns
   • Requirements
   • Solutions

5. Regional Compliance

   • Compliance per landing zone
   • Regulatory requirements
   • Audit capabilities

6. Federated Identity

   • Identity across regions
   • SSO patterns
   • Multi-national identity

7. Network Connectivity

   • Cross-region connectivity
   • Security patterns
   • Performance considerations

8. Use Cases

   • Detailed scenarios
   • Implementation examples

9. Landing Zone Templates

   • Templates for common patterns
   • Automation
   • Deployment guides

10. Integration with Existing Infrastructure

    • Proxmox integration
    • Kubernetes integration
    • Cloudflare integration

7. Migration Guide

File: docs/phoenix/MIGRATION_GUIDE.md

Sections:

1. Migration from Existing Model

   • Current tenant-based model
   • Migration to Client/Tenant/Subscription model
   • Data migration
   • Identity migration

2. Migration from Azure

   • Step-by-step guide
   • Data migration
   • Identity migration
   • Application migration
   • Cost analysis

3. Migration from AWS

   • Step-by-step guide
   • Data migration
   • Identity migration
   • Application migration
   • Cost analysis

4. Migration Planning

   • Assessment
   • Timeline
   • Risk mitigation
   • Rollback plans

5. Migration Tools

   • Available tools
   • Automation scripts
   • Validation tools

---

Implementation Details

Data Model Extensions

Extend existing GraphQL schema in docs/architecture/data-model.md to include:

Client (Billing Profile):

type Client {
  id: ID!
  name: String!
  legalEntity: String!
  contract: Contract
  msa: MSA
  invoicingConfig: InvoicingConfig
  paymentInstruments: [PaymentInstrument!]!
  costCenters: [CostCenter!]!
  tenants: [Tenant!]!
  createdAt: DateTime!
  updatedAt: DateTime!
  metadata: JSON
}

Tenant (extended):

type Tenant {
  id: ID!
  name: String!
  primaryDomains: [String!]!
  identityProvider: IdentityProvider
  rbacNamespace: String!
  dataResidencyFlags: [DataResidencyFlag!]!
  complianceProfile: ComplianceProfile
  subscriptions: [Subscription!]!
  environments: [Environment!]!
  regions: [Region!]!
  keycloakRealmId: String
  createdAt: DateTime!
  updatedAt: DateTime!
  metadata: JSON
}

Subscription:

type Subscription {
  id: ID!
  name: String!
  tenant: Tenant!
  client: Client!
  serviceBundles: [ServiceBundle!]!
  quotas: Quotas
  limits: Limits
  costTracking: CostTracking
  policyPacks: [PolicyPack!]!
  featureEntitlements: [FeatureEntitlement!]!
  environments: [Environment!]!
  regions: [Region!]!
  type: SubscriptionType!
  createdAt: DateTime!
  updatedAt: DateTime!
  metadata: JSON
}

enum SubscriptionType {
  SHARED_PLATFORM
  PRODUCT
  SANDBOX
  INNOVATION
}

Environment (extended):

type Environment {
  id: ID!
  name: String!
  type: EnvironmentType!
  subscription: Subscription!
  networkIsolation: NetworkIsolation
  dataIsolation: DataIsolation
  deploymentPolicies: [DeploymentPolicy!]!
  runtimeSecrets: [Secret!]!
  complianceOverlays: [ComplianceOverlay!]!
  region: Region
  promotionFlow: PromotionFlow
  createdAt: DateTime!
  updatedAt: DateTime!
  metadata: JSON
}

enum EnvironmentType {
  DEV
  INT
  UAT
  STAGING
  PROD
  REGULATED
  SOVEREIGN
  AIR_GAPPED
}

Content Hierarchy:

type Enterprise {
  id: ID!
  name: String!
  portfolios: [Portfolio!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Portfolio {
  id: ID!
  name: String!
  enterprise: Enterprise!
  products: [Product!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Product {
  id: ID!
  name: String!
  portfolio: Portfolio!
  applications: [Application!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Application {
  id: ID!
  name: String!
  product: Product!
  components: [Component!]!
  gitRepos: [GitRepo!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Component {
  id: ID!
  name: String!
  application: Application!
  contentType: ContentType!
  content: Content!
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum ContentType {
  SOURCE_CODE
  IAC
  PIPELINE
  CONFIG_TEMPLATE
  DOCUMENTATION
  DATA_SCHEMA
  AI_MODEL
  PROMPT
}

Landing Zone:

type LandingZone {
  id: ID!
  name: String!
  region: Region!
  tenant: Tenant
  subscription: Subscription
  sovereignCloud: Boolean!
  dataResidency: DataResidency!
  complianceProfile: ComplianceProfile!
  networkConnectivity: [NetworkConnection!]!
  createdAt: DateTime!
  updatedAt: DateTime!
  metadata: JSON
}

Integration Points

Document integration with:

• Existing Keycloak identity management (sovereign identity, federated identity)
• Current infrastructure (Proxmox, Kubernetes, Cloudflare)
• Multi-region infrastructure coordination
• Git/GitOps workflows (ArgoCD)
• CI/CD pipelines
• Monitoring and observability
• Compliance and audit systems (multi-national)
• Government identity providers (Entra, Okta, etc.) - federated
• Cross-region governance systems

---

File Structure

docs/phoenix/
├── OPERATING_MODEL.md              # Core operating model (comprehensive)
├── OPERATING_MODEL_DIAGRAMS.md     # Visual diagrams (mermaid)
├── CLOUD_PROVIDER_MAPPING.md       # Azure/AWS/hybrid mapping + competitive analysis
├── MVP_CONTROL_PLANE.md            # Minimum viable implementation
├── PRODUCT_SPEC.md                 # Client-facing specification for sovereign governments
├── MULTI_REGION_LANDING_ZONES.md   # Multi-region landing zones guide
├── MIGRATION_GUIDE.md              # Migration guide (NEW)
├── PLAN_REVIEW.md                  # Review document (existing)
├── UPDATED_PLAN.md                 # This document
└── README.md                       # Index/overview (update existing or create)

---

Key Principles

1. Separation of Concerns: Each plane operates independently with ID-based references
2. Enterprise Scale: Support for large multi-tenant deployments
3. Security Boundaries: Tenant as security blast-radius boundary
4. DevOps Velocity: Content & DevOps plane separate from billing/tenancy
5. Compliance Ready: Audit trails, data residency, regulatory compliance
6. Cloud Agnostic: Works with Azure, AWS, hybrid, and sovereign deployments
7. Sovereign First: Built for sovereign governments with air-gapped capabilities
8. Competitive Advantage: Superior multi-tenancy, billing, and sovereignty vs Azure/AWS
9. Multi-Region Native: Designed for international/multi-national sovereign governments
10. Decentralized Architecture: Supports distributed governance and sovereignty
11. Landing Zone Patterns: Multi-region sovereign cloud deployments
12. Cross-Border Sovereignty: Enables sovereignty across distributed regions

---

Implementation Order

Phase 1: Foundation (Week 1-2)

1. Create OPERATING_MODEL.md with all sections
2. Resolve entity model inconsistencies
3. Document key rules and constraints
4. Create entity schemas

Phase 2: Visuals and Integration (Week 3)

1. Create OPERATING_MODEL_DIAGRAMS.md with all diagrams
2. Document integration mapping
3. Create glossary

Phase 3: Competitive and MVP (Week 4)

1. Create CLOUD_PROVIDER_MAPPING.md
2. Create MVP_CONTROL_PLANE.md
3. Expand competitive analysis

Phase 4: Specialized Guides (Week 5)

1. Create MULTI_REGION_LANDING_ZONES.md
2. Create MIGRATION_GUIDE.md
3. Create PRODUCT_SPEC.md

Phase 5: Updates and Cross-References (Week 6)

1. Update existing documentation indexes
2. Add cross-references
3. Update existing tenant/billing docs with migration notes
4. Final review and polish

---

Success Criteria

1. ✅ All five control planes fully documented
2. ✅ Entity model inconsistencies resolved
3. ✅ Content & DevOps plane fully detailed
4. ✅ All key rules explicitly documented
5. ✅ Integration mapping complete
6. ✅ Multi-region and decentralized architecture fully explained
7. ✅ Multi-national government use cases documented
8. ✅ Migration paths clearly defined
9. ✅ Competitive analysis comprehensive
10. ✅ All diagrams created
11. ✅ Glossary complete
12. ✅ Cross-references added
13. ✅ Existing docs updated with migration notes

---

Next Steps

1. Begin Phase 1 implementation
2. Review each deliverable as completed
3. Update plan based on findings
4. Ensure consistency across all documents
5. Validate against existing infrastructure
6. Get stakeholder review