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)**:
```graphql
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):
```graphql
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**:
```graphql
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):
```graphql
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**:
```graphql
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**:
```graphql
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