Co-authored-by: Cursor <cursoragent@cursor.com>
24 KiB
Phoenix MVP Control Plane Specification
Minimum Viable Product (MVP) Definition for Phoenix Operating Model
This document defines the MVP scope for the Phoenix operating model, including required APIs, data model extensions, implementation priorities, and sovereign government MVP requirements.
Executive Summary
The Phoenix MVP Control Plane provides the minimum set of capabilities required to support sovereign government deployments with the five control planes (Commercial, Tenancy, Subscription, Environment, Content & DevOps). The MVP focuses on core functionality while maintaining the separation of concerns and enabling future expansion.
MVP Principles:
- Core Functionality First: Essential features for sovereign government deployments
- Separation of Concerns: All five control planes included in MVP
- Sovereign Capabilities: Support for sovereign, regulated, and air-gapped environments
- Multi-Region Ready: Foundation for multi-region deployments
- Integration Ready: Integration with existing infrastructure (Proxmox, Kubernetes, Keycloak)
MVP Scope Definition
What's In MVP
Commercial Plane MVP
- ✅ Client (Billing Profile) entity
- ✅ Basic billing aggregation
- ✅ Invoice generation
- ✅ Cost tracking per Client
- ✅ Payment instrument management
- ⚠️ Cost centers (basic support)
- ❌ Advanced chargeback (future)
Tenancy Plane MVP
- ✅ Tenant entity
- ✅ Primary domain management
- ✅ Keycloak realm integration (1:1)
- ✅ Basic RBAC namespace
- ✅ Data residency flags
- ✅ Compliance profile (basic)
- ⚠️ Multi-region tenants (basic support)
- ❌ Advanced federated identity (future)
Subscription Plane MVP
- ✅ Subscription entity
- ✅ Service bundles (compute, storage, networking)
- ✅ Basic quotas and limits
- ✅ Cost tracking per Subscription
- ✅ Policy packs (security, networking)
- ✅ Subscription types (Product, Sandbox)
- ⚠️ Shared Platform Subscription (basic)
- ❌ Innovation Subscription (future)
Environment Plane MVP
- ✅ Environment entity
- ✅ Environment types (DEV, INT, UAT, STAGING, PROD)
- ✅ Network isolation (basic)
- ✅ Data isolation (basic)
- ✅ Deployment policies (basic)
- ✅ Promotion flow (policy-driven)
- ⚠️ REGULATED environment (basic)
- ⚠️ SOVEREIGN environment (basic)
- ❌ AIR-GAPPED environment (future)
Content & DevOps Plane MVP
- ✅ Enterprise content hierarchy (basic)
- ✅ Git repository integration
- ✅ CI/CD pipeline integration (basic)
- ✅ Artifact registry integration
- ✅ Policy-driven promotion (basic)
- ⚠️ Approval workflows (basic)
- ❌ Advanced governance (future)
What's Not In MVP (Future)
- Advanced chargeback and cost allocation
- Advanced federated identity across regions
- Innovation Subscription type
- AIR-GAPPED environment type
- Advanced content governance
- Multi-region promotion flows
- Advanced compliance automation
- Blockchain integration (optional in MVP)
MVP for Each Control Plane
Commercial Plane MVP
Core Features
Client Entity:
- Create, read, update, delete Client
- Legal entity information
- Contract and MSA management
- Invoicing configuration
- Payment instruments
Billing:
- Usage aggregation from Subscriptions
- Cost tracking per Client
- Invoice generation (PDF, JSON)
- Payment processing (basic)
Cost Centers:
- Basic cost center structure
- Cost allocation to cost centers
- Cost center reporting
Required APIs
# Client Management
type Mutation {
createClient(input: CreateClientInput!): Client!
updateClient(id: ID!, input: UpdateClientInput!): Client!
deleteClient(id: ID!): Boolean!
}
type Query {
client(id: ID!): Client
clients(filter: ClientFilter): [Client!]!
}
# Billing
type Query {
billing(clientId: ID!, timeRange: TimeRange!): BillingData!
invoices(clientId: ID!, filter: InvoiceFilter): [Invoice!]!
}
type Mutation {
createInvoice(clientId: ID!, period: BillingPeriod!): Invoice!
processPayment(invoiceId: ID!, payment: PaymentInput!): Payment!
}
Data Model Extensions
type Client {
id: ID!
name: String!
legalEntity: LegalEntity!
contract: Contract
invoicingConfig: InvoicingConfig!
paymentInstruments: [PaymentInstrument!]!
costCenters: [CostCenter!]!
tenants: [Tenant!]!
createdAt: DateTime!
updatedAt: DateTime!
}
type BillingData {
client: Client!
totalCost: Float!
currency: String!
period: TimeRange!
bySubscription: [SubscriptionCost!]!
byCostCenter: [CostCenterCost!]!
}
Tenancy Plane MVP
Core Features
Tenant Entity:
- Create, read, update, delete Tenant
- Primary domain management
- Keycloak realm integration (automatic 1:1)
- RBAC namespace
- Data residency flags
- Compliance profile
Identity:
- Keycloak realm creation per Tenant
- Basic identity provider configuration
- User management (via Keycloak)
Security:
- Tenant as security boundary
- Network isolation per Tenant
- RBAC namespace isolation
Required APIs
# Tenant Management
type Mutation {
createTenant(input: CreateTenantInput!): Tenant!
updateTenant(id: ID!, input: UpdateTenantInput!): Tenant!
deleteTenant(id: ID!): Boolean!
}
type Query {
tenant(id: ID!): Tenant
tenants(filter: TenantFilter): [Tenant!]!
}
# Identity
type Mutation {
configureIdentityProvider(tenantId: ID!, provider: IdentityProviderInput!): IdentityProvider!
syncKeycloakRealm(tenantId: ID!): KeycloakRealm!
}
Data Model Extensions
type Tenant {
id: ID!
name: String!
primaryDomains: [String!]!
identityProvider: IdentityProvider!
rbacNamespace: String!
dataResidencyFlags: [DataResidencyFlag!]!
complianceProfile: ComplianceProfile!
client: Client!
subscriptions: [Subscription!]!
keycloakRealmId: String
createdAt: DateTime!
updatedAt: DateTime!
}
Subscription Plane MVP
Core Features
Subscription Entity:
- Create, read, update, delete Subscription
- Service bundles (compute, storage, networking)
- Quotas and limits
- Policy packs (security, networking)
- Subscription types (Product, Sandbox)
Quotas:
- Compute quotas (vCPU, memory, instances)
- Storage quotas (total, per-instance)
- Network quotas (bandwidth, egress)
Policy Packs:
- Security policies
- Networking policies
- Basic data access policies
Required APIs
# Subscription Management
type Mutation {
createSubscription(input: CreateSubscriptionInput!): Subscription!
updateSubscription(id: ID!, input: UpdateSubscriptionInput!): Subscription!
deleteSubscription(id: ID!): Boolean!
}
type Query {
subscription(id: ID!): Subscription
subscriptions(filter: SubscriptionFilter): [Subscription!]!
}
# Quotas
type Mutation {
updateQuotas(subscriptionId: ID!, quotas: QuotasInput!): Quotas!
checkQuota(subscriptionId: ID!, resource: ResourceType!): QuotaStatus!
}
Data Model Extensions
type Subscription {
id: ID!
name: String!
tenant: Tenant!
client: Client!
type: SubscriptionType!
serviceBundles: [ServiceBundle!]!
quotas: Quotas!
limits: Limits!
policyPacks: [PolicyPack!]!
environments: [Environment!]!
createdAt: DateTime!
updatedAt: DateTime!
}
enum SubscriptionType {
PRODUCT
SANDBOX
}
Environment Plane MVP
Core Features
Environment Entity:
- Create, read, update, delete Environment
- Environment types (DEV, INT, UAT, STAGING, PROD)
- Network isolation (basic)
- Data isolation (basic)
- Deployment policies (basic)
- Promotion flow (policy-driven)
Promotion:
- Policy-driven promotion between environments
- Basic approval workflows
- Automated promotion (DEV → INT → UAT)
- Manual approval (UAT → STAGING → PROD)
Required APIs
# Environment Management
type Mutation {
createEnvironment(input: CreateEnvironmentInput!): Environment!
updateEnvironment(id: ID!, input: UpdateEnvironmentInput!): Environment!
deleteEnvironment(id: ID!): Boolean!
}
type Query {
environment(id: ID!): Environment
environments(filter: EnvironmentFilter): [Environment!]!
}
# Promotion
type Mutation {
promoteArtifact(input: PromoteArtifactInput!): PromotionResult!
approvePromotion(promotionId: ID!, approved: Boolean!): PromotionResult!
}
Data Model Extensions
type Environment {
id: ID!
name: String!
type: EnvironmentType!
subscription: Subscription!
networkIsolation: NetworkIsolation!
dataIsolation: DataIsolation!
deploymentPolicies: [DeploymentPolicy!]!
promotionFlow: PromotionFlow
createdAt: DateTime!
updatedAt: DateTime!
}
enum EnvironmentType {
DEV
INT
UAT
STAGING
PROD
REGULATED
SOVEREIGN
}
Content & DevOps Plane MVP
Core Features
Content Hierarchy:
- Enterprise, Portfolio, Product, Application, Component entities
- Basic ownership and governance
- Git repository mapping
Git Integration:
- Git repository management
- Branch strategy enforcement (basic)
- Protected branches (PROD)
CI/CD Integration:
- CI/CD pipeline integration
- Artifact registry integration
- Policy-driven promotion (basic)
- Basic approval workflows
Required APIs
# Content Management
type Mutation {
createEnterprise(input: CreateEnterpriseInput!): Enterprise!
createPortfolio(input: CreatePortfolioInput!): Portfolio!
createProduct(input: CreateProductInput!): Product!
createApplication(input: CreateApplicationInput!): Application!
createComponent(input: CreateComponentInput!): Component!
}
type Query {
enterprise(id: ID!): Enterprise
portfolio(id: ID!): Portfolio
product(id: ID!): Product
application(id: ID!): Application
component(id: ID!): Component
}
# Git Integration
type Mutation {
createGitRepo(input: CreateGitRepoInput!): GitRepo!
configureBranchProtection(repoId: ID!, branch: String!, protection: BranchProtectionInput!): BranchProtection!
}
Data Model Extensions
type Enterprise {
id: ID!
name: String!
portfolios: [Portfolio!]!
ownership: Ownership!
createdAt: DateTime!
updatedAt: DateTime!
}
type Application {
id: ID!
name: String!
product: Product!
components: [Component!]!
gitRepos: [GitRepo!]!
ownership: Ownership!
createdAt: DateTime!
updatedAt: DateTime!
}
Multi-Region MVP Requirements
Basic Multi-Region Support
In MVP:
- ✅ Multi-region Tenant support (basic)
- ✅ Regional data residency flags
- ✅ Regional landing zones (basic)
- ⚠️ Cross-region coordination (basic)
- ❌ Federated governance (future)
Not In MVP:
- Advanced cross-region coordination
- Federated governance
- Multi-region promotion flows
- Cross-region audit aggregation
Regional Landing Zones
MVP Scope:
- Basic landing zone per region
- Regional data residency enforcement
- Basic cross-region connectivity
- Regional compliance profiles
Decentralized Architecture MVP
Basic Decentralized Support
In MVP:
- ✅ Regional control plane deployment (basic)
- ✅ Event-driven coordination (basic)
- ⚠️ Federated identity (basic)
- ❌ Advanced federated governance (future)
Not In MVP:
- Advanced federated governance
- Cross-region conflict resolution
- Advanced eventual consistency
Sovereign Government MVP Requirements
Compliance Capabilities
In MVP:
- ✅ Compliance profiles (ISO, SOC, HIPAA)
- ✅ Basic audit logging
- ✅ Data residency flags
- ⚠️ REGULATED environment type
- ⚠️ SOVEREIGN environment type
- ❌ AIR-GAPPED environment type (future)
Audit Capabilities
In MVP:
- ✅ Basic audit logging
- ✅ Access audit trails
- ✅ Deployment audit trails
- ⚠️ Cross-region audit aggregation (basic)
- ❌ Advanced audit analytics (future)
Air-Gapped Support
Not In MVP:
- AIR-GAPPED environment type
- Complete network isolation
- Air-gapped deployment automation
Future:
- AIR-GAPPED environment type
- Air-gapped landing zones
- Air-gapped deployment automation
Required APIs and Services
Control Plane APIs
Commercial Plane API
- Service:
commercial-service - Endpoints: Client CRUD, Billing, Invoicing
- Database: PostgreSQL (clients, billing, invoices)
- Integration: Billing aggregation from Subscriptions
Tenancy Plane API
- Service:
tenancy-service - Endpoints: Tenant CRUD, Identity Provider Configuration
- Database: PostgreSQL (tenants, identity providers)
- Integration: Keycloak (realm management)
Subscription Plane API
- Service:
subscription-service - Endpoints: Subscription CRUD, Quota Management, Policy Packs
- Database: PostgreSQL (subscriptions, quotas, policies)
- Integration: Environment Plane (quota enforcement)
Environment Plane API
- Service:
environment-service - Endpoints: Environment CRUD, Promotion, Deployment
- Database: PostgreSQL (environments, promotions)
- Integration: Content & DevOps Plane (deployment), Infrastructure (resource provisioning)
Content & DevOps Plane API
- Service:
content-service - Endpoints: Content Hierarchy CRUD, Git Integration, CI/CD
- Database: PostgreSQL (enterprises, portfolios, products, applications, components)
- Integration: Git (repositories), CI/CD (pipelines), Environment Plane (deployment)
Integration Services
Keycloak Integration
- Service:
keycloak-integration - Function: Tenant realm management, user sync
- Integration: Tenancy Plane API
Infrastructure Integration
- Service:
infrastructure-integration - Function: Proxmox, Kubernetes, Cloudflare integration
- Integration: Environment Plane API, Subscription Plane API
Git Integration
- Service:
git-integration - Function: Git repository management, branch protection
- Integration: Content & DevOps Plane API
CI/CD Integration
- Service:
cicd-integration - Function: CI/CD pipeline integration, artifact management
- Integration: Content & DevOps Plane API, Environment Plane API
Data Model Extensions
Database Schema Extensions
Clients Table
CREATE TABLE clients (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
legal_entity JSONB NOT NULL,
contract JSONB,
invoicing_config JSONB NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Tenants Table
CREATE TABLE tenants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
client_id UUID NOT NULL REFERENCES clients(id),
primary_domains TEXT[] NOT NULL,
identity_provider JSONB NOT NULL,
rbac_namespace VARCHAR(255) NOT NULL,
data_residency_flags JSONB[],
compliance_profile JSONB,
keycloak_realm_id VARCHAR(255),
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Subscriptions Table
CREATE TABLE subscriptions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
tenant_id UUID NOT NULL REFERENCES tenants(id),
client_id UUID NOT NULL REFERENCES clients(id),
type VARCHAR(50) NOT NULL,
service_bundles JSONB[] NOT NULL,
quotas JSONB NOT NULL,
limits JSONB NOT NULL,
policy_packs JSONB[],
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Environments Table
CREATE TABLE environments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
subscription_id UUID NOT NULL REFERENCES subscriptions(id),
type VARCHAR(50) NOT NULL,
network_isolation JSONB NOT NULL,
data_isolation JSONB NOT NULL,
deployment_policies JSONB[],
promotion_flow JSONB,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Content Hierarchy Tables
CREATE TABLE enterprises (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
ownership JSONB NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE portfolios (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
enterprise_id UUID NOT NULL REFERENCES enterprises(id),
ownership JSONB NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE products (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
portfolio_id UUID NOT NULL REFERENCES portfolios(id),
ownership JSONB NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE applications (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
product_id UUID NOT NULL REFERENCES products(id),
ownership JSONB NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE components (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
application_id UUID NOT NULL REFERENCES applications(id),
content_type VARCHAR(50) NOT NULL,
content JSONB NOT NULL,
version VARCHAR(50) NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
GraphQL Schema Extensions
See docs/phoenix/OPERATING_MODEL.md for complete GraphQL schema definitions.
Implementation Priorities
Priority 1: Core Entities (Weeks 1-2)
-
Commercial Plane
- Client entity
- Basic billing aggregation
- Invoice generation
-
Tenancy Plane
- Tenant entity
- Keycloak integration
- Basic RBAC
-
Subscription Plane
- Subscription entity
- Basic quotas
- Policy packs
-
Environment Plane
- Environment entity
- Basic isolation
- Promotion flow
-
Content & DevOps Plane
- Content hierarchy
- Git integration
- Basic CI/CD
Priority 2: Integration (Weeks 3-4)
-
Keycloak Integration
- Realm creation per Tenant
- User sync
- Identity provider configuration
-
Infrastructure Integration
- Proxmox integration
- Kubernetes integration
- Cloudflare integration
-
Git Integration
- Repository management
- Branch protection
- CI/CD integration
Priority 3: Advanced Features (Weeks 5-6)
-
Multi-Region Support
- Regional landing zones
- Cross-region coordination
- Regional data residency
-
Compliance
- Compliance profiles
- Audit logging
- REGULATED/SOVEREIGN environments
-
Advanced Promotion
- Approval workflows
- Policy validation
- Automated promotion
Dependencies Between Features
Dependency Graph
Client Entity
└── Tenant Entity (requires Client)
└── Subscription Entity (requires Tenant)
└── Environment Entity (requires Subscription)
└── Content Deployment (requires Environment)
Keycloak Integration
└── Tenant Entity (requires Keycloak)
Infrastructure Integration
└── Environment Entity (requires Infrastructure)
Git Integration
└── Content Hierarchy (requires Git)
CI/CD Integration
└── Git Integration (requires CI/CD)
└── Environment Entity (requires CI/CD)
Critical Path
- Week 1: Client, Tenant, Subscription entities
- Week 2: Environment entity, Keycloak integration
- Week 3: Content hierarchy, Git integration
- Week 4: Infrastructure integration, CI/CD integration
- Week 5: Multi-region support, compliance
- Week 6: Advanced features, testing, documentation
Risk Assessment Per Feature
High Risk Features
-
Keycloak Integration
- Risk: Realm creation and sync complexity
- Mitigation: Phased rollout, extensive testing
-
Multi-Region Support
- Risk: Cross-region coordination complexity
- Mitigation: Start with basic support, expand gradually
-
Promotion Flow
- Risk: Policy validation complexity
- Mitigation: Start with basic policies, expand gradually
Medium Risk Features
-
Billing Aggregation
- Risk: Performance with large datasets
- Mitigation: Efficient aggregation algorithms, caching
-
Infrastructure Integration
- Risk: Integration complexity with multiple systems
- Mitigation: Well-defined integration patterns, testing
Low Risk Features
-
Content Hierarchy
- Risk: Low - standard CRUD operations
- Mitigation: Standard implementation patterns
-
Basic Quotas
- Risk: Low - standard quota management
- Mitigation: Standard implementation patterns
Integration with Existing Infrastructure
Proxmox Integration
MVP Scope:
- Environment → Proxmox resource pool mapping
- Subscription → Proxmox quota mapping
- Tenant → Proxmox access control mapping
Integration Points:
- Proxmox API for resource provisioning
- Proxmox quota management
- Proxmox access control
Kubernetes Integration
MVP Scope:
- Environment → Kubernetes namespace mapping
- Subscription → Kubernetes ResourceQuota mapping
- Tenant → Kubernetes RBAC namespace mapping
Integration Points:
- Kubernetes API for namespace management
- Kubernetes ResourceQuota API
- Kubernetes RBAC API
Keycloak Integration
MVP Scope:
- Tenant → Keycloak realm (1:1)
- Identity provider configuration
- User sync
Integration Points:
- Keycloak Admin API
- Keycloak Realm API
- Keycloak Identity Provider API
Cloudflare Integration
MVP Scope:
- Tenant → Cloudflare Access Policy mapping
- Environment → Cloudflare Tunnel mapping
- Region → Cloudflare Tunnel endpoint mapping
Integration Points:
- Cloudflare API for Access Policies
- Cloudflare Tunnel API
- Cloudflare Zero Trust API
ArgoCD Integration
MVP Scope:
- Application → ArgoCD Application mapping
- Environment → ArgoCD Target Environment mapping
- Subscription → ArgoCD Resource Quota mapping
Integration Points:
- ArgoCD API for Application management
- ArgoCD API for Environment configuration
- ArgoCD API for Resource Quota management
Success Criteria for MVP
Functional Criteria
- ✅ All five control planes operational
- ✅ Core entities (Client, Tenant, Subscription, Environment, Content) functional
- ✅ Keycloak integration working (1:1 Tenant to Realm)
- ✅ Basic infrastructure integration (Proxmox, Kubernetes)
- ✅ Basic CI/CD integration
- ✅ Policy-driven promotion working
- ✅ Basic multi-region support
- ✅ Basic compliance support
Performance Criteria
- ✅ API response times < 200ms (p95)
- ✅ Billing aggregation completes in < 5 seconds
- ✅ Tenant creation completes in < 30 seconds
- ✅ Environment provisioning completes in < 2 minutes
Security Criteria
- ✅ All APIs authenticated and authorized
- ✅ Tenant isolation enforced
- ✅ Audit logging functional
- ✅ Data residency flags enforced
Compliance Criteria
- ✅ Compliance profiles functional
- ✅ Audit trails complete
- ✅ REGULATED and SOVEREIGN environments supported
Next Steps After MVP
-
Advanced Features
- AIR-GAPPED environment type
- Advanced federated identity
- Advanced chargeback
- Innovation Subscription type
-
Enhanced Multi-Region
- Advanced cross-region coordination
- Federated governance
- Multi-region promotion flows
-
Advanced Compliance
- Automated compliance checking
- Advanced audit analytics
- Blockchain integration (optional)
-
Performance Optimization
- Caching strategies
- Database optimization
- API performance tuning
References
Phoenix Operating Model Documentation
- Operating Model - Core operating model documentation
- Architecture Diagrams - Visual diagrams of the operating model
- Cloud Provider Mapping - Azure/AWS mapping and competitive analysis
- Multi-Region Landing Zones - Landing zone patterns and deployment
- Migration Guide - Migration from existing systems and cloud providers
Architecture Documentation
- Data Model - GraphQL schema and data model
Last Updated: 2025-01-09
Version: 1.0
Status: MVP Control Plane Specification Complete