d-bis/Sankofa
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial Phoenix Sankofa Cloud setup

Browse Source 
- Complete project structure with Next.js frontend
- GraphQL API backend with Apollo Server
- Portal application with NextAuth
- Crossplane Proxmox provider
- GitOps configurations
- CI/CD pipelines
- Testing infrastructure (Vitest, Jest, Go tests)
- Error handling and monitoring
- Security hardening
- UI component library
- Documentation
This commit is contained in:
defiQUG
2025-11-28 12:54:33 -08:00
commit 6f28146ac3
229 changed files with 43136 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

638
docs/architecture/data-model.md Normal file
View File

@@ -0,0 +1,638 @@
# Phoenix Sankofa Cloud: Data Model & GraphQL Schema
## Overview
The data model for **Phoenix Sankofa Cloud** is designed as a **graph-oriented structure** that represents:
* Infrastructure resources (regions, clusters, nodes, services)
* Relationships between resources (networks, dependencies, policies)
* Metrics and telemetry (performance, health, cost)
* Well-Architected Framework assessments
* Identity and access management
* Cultural intelligence and regional context
---
## Core GraphQL Schema
### Resource Types
```graphql
# Base resource interface
interface Resource {
id: ID!
name: String!
type: ResourceType!
region: Region
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
}
enum ResourceType {
REGION
SITE
CLUSTER
NODE
VM
POD
SERVICE
NETWORK
STORAGE
TUNNEL
POLICY
}
# Region - Top-level geographic location
type Region implements Resource {
id: ID!
name: String!
type: ResourceType!
code: String! # e.g., "us-east-1"
country: String
coordinates: Coordinates
sites: [Site!]!
clusters: [Cluster!]!
networks: [Network!]!
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
culturalContext: CulturalContext
}
# Site - Physical or logical location within a region
type Site implements Resource {
id: ID!
name: String!
type: ResourceType!
region: Region!
clusters: [Cluster!]!
networks: [Network!]!
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
}
# Cluster - Compute cluster (Kubernetes, Proxmox, etc.)
type Cluster implements Resource {
id: ID!
name: String!
type: ResourceType!
region: Region
site: Site
nodes: [Node!]!
services: [Service!]!
provider: ProviderType
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
health: HealthStatus!
metrics: ClusterMetrics
}
# Node - Individual compute node
type Node implements Resource {
id: ID!
name: String!
type: ResourceType!
cluster: Cluster!
vms: [VM!]!
pods: [Pod!]!
provider: ProviderType
specs: NodeSpecs
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
health: HealthStatus!
metrics: NodeMetrics
}
# Service - Application service
type Service implements Resource {
id: ID!
name: String!
type: ResourceType!
cluster: Cluster
pods: [Pod!]!
dependencies: [Service!]! # Services this depends on
dependents: [Service!]! # Services that depend on this
networks: [Network!]!
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
health: HealthStatus!
metrics: ServiceMetrics
}
# Network - Network resource (VPC, subnet, tunnel, etc.)
type Network implements Resource {
id: ID!
name: String!
type: ResourceType!
region: Region
cidr: String
connections: [NetworkConnection!]!
services: [Service!]!
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
}
# Network Connection - Edge between networks
type NetworkConnection {
id: ID!
from: Network!
to: Network!
type: ConnectionType!
latency: Float
bandwidth: Float
status: ConnectionStatus!
createdAt: DateTime!
updatedAt: DateTime!
}
enum ConnectionType {
PEERING
VPN
TUNNEL
DIRECT
}
enum ConnectionStatus {
ACTIVE
INACTIVE
DEGRADED
FAILED
}
# Storage - Storage resource
type Storage implements Resource {
id: ID!
name: String!
type: ResourceType!
region: Region
cluster: Cluster
size: Float!
used: Float!
createdAt: DateTime!
updatedAt: DateTime!
metadata: JSON
tags: [Tag!]!
metrics: StorageMetrics
}
```
### Well-Architected Framework
```graphql
# Well-Architected Framework Pillar
type Pillar {
id: ID!
name: String!
code: PillarCode!
description: String
controls: [Control!]!
resources: [Resource!]!
}
enum PillarCode {
SECURITY
RELIABILITY
COST_OPTIMIZATION
PERFORMANCE_EFFICIENCY
OPERATIONAL_EXCELLENCE
SUSTAINABILITY
}
# Control - Specific control within a pillar
type Control {
id: ID!
name: String!
code: String!
pillar: Pillar!
description: String
findings: [Finding!]!
resources: [Resource!]!
}
# Finding - Assessment finding for a control
type Finding {
id: ID!
control: Control!
resource: Resource!
status: FindingStatus!
severity: Severity!
title: String!
description: String
recommendation: String
createdAt: DateTime!
updatedAt: DateTime!
}
enum FindingStatus {
PASS
FAIL
WARNING
INFO
NOT_APPLICABLE
}
enum Severity {
CRITICAL
HIGH
MEDIUM
LOW
INFO
}
# Risk - Risk associated with a resource
type Risk {
id: ID!
resource: Resource!
pillar: Pillar
severity: Severity!
title: String!
description: String
mitigation: String
createdAt: DateTime!
updatedAt: DateTime!
}
```
### Metrics & Telemetry
```graphql
# Metrics - Time-series metrics
type Metrics {
resource: Resource!
metricType: MetricType!
values: [MetricValue!]!
timeRange: TimeRange!
}
enum MetricType {
CPU_USAGE
MEMORY_USAGE
NETWORK_THROUGHPUT
NETWORK_LATENCY
STORAGE_IOPS
REQUEST_RATE
ERROR_RATE
COST
HEALTH_SCORE
}
type MetricValue {
timestamp: DateTime!
value: Float!
labels: JSON
}
type TimeRange {
start: DateTime!
end: DateTime!
}
# Health Status
enum HealthStatus {
HEALTHY
DEGRADED
UNHEALTHY
UNKNOWN
}
# Cluster Metrics
type ClusterMetrics {
cpuUsage: Float!
memoryUsage: Float!
nodeCount: Int!
healthyNodes: Int!
unhealthyNodes: Int!
totalCost: Float!
healthScore: Float!
}
# Node Metrics
type NodeMetrics {
cpuUsage: Float!
memoryUsage: Float!
diskUsage: Float!
networkThroughput: Float!
healthScore: Float!
}
# Service Metrics
type ServiceMetrics {
requestRate: Float!
errorRate: Float!
latency: Float!
availability: Float!
healthScore: Float!
}
# Storage Metrics
type StorageMetrics {
used: Float!
available: Float!
iops: Float!
throughput: Float!
}
```
### Cultural Intelligence
```graphql
# Cultural Context - Cultural information for a region
type CulturalContext {
region: Region!
language: String
timezone: String
culturalNorms: JSON
complianceRequirements: [ComplianceRequirement!]!
dataResidency: DataResidency
}
# Data Residency
type DataResidency {
region: Region!
requirements: [String!]!
compliance: [ComplianceRequirement!]!
}
```
### Identity & Access
```graphql
# Identity - User or service identity
type Identity {
id: ID!
type: IdentityType!
name: String!
email: String
roles: [Role!]!
permissions: [Permission!]!
createdAt: DateTime!
updatedAt: DateTime!
}
enum IdentityType {
USER
SERVICE
SYSTEM
}
# Role - Access role
type Role {
id: ID!
name: String!
permissions: [Permission!]!
resources: [Resource!]!
}
# Permission - Access permission
type Permission {
id: ID!
action: Action!
resource: Resource
conditions: JSON
}
enum Action {
READ
WRITE
DELETE
ADMIN
}
```
### Queries
```graphql
type Query {
# Resource queries
resource(id: ID!): Resource
resources(filter: ResourceFilter): [Resource!]!
region(id: ID!): Region
regions: [Region!]!
cluster(id: ID!): Cluster
clusters(filter: ClusterFilter): [Cluster!]!
# Network queries
network(id: ID!): Network
networks(filter: NetworkFilter): [Network!]!
networkTopology(regionId: ID): NetworkTopology!
# Service queries
service(id: ID!): Service
services(filter: ServiceFilter): [Service!]!
serviceDependencies(serviceId: ID!): [Service!]!
# Well-Architected Framework
pillar(code: PillarCode!): Pillar
pillars: [Pillar!]!
findings(filter: FindingFilter): [Finding!]!
risks(resourceId: ID): [Risk!]!
# Metrics
metrics(resourceId: ID!, metricType: MetricType!, timeRange: TimeRange!): Metrics!
# Health
health(resourceId: ID!): HealthStatus!
# Cultural context
culturalContext(regionId: ID!): CulturalContext
}
```
### Mutations
```graphql
type Mutation {
# Resource mutations
createResource(input: CreateResourceInput!): Resource!
updateResource(id: ID!, input: UpdateResourceInput!): Resource!
deleteResource(id: ID!): Boolean!
# Finding mutations
createFinding(input: CreateFindingInput!): Finding!
updateFinding(id: ID!, input: UpdateFindingInput!): Finding!
# Risk mutations
createRisk(input: CreateRiskInput!): Risk!
updateRisk(id: ID!, input: UpdateRiskInput!): Risk!
}
```
### Subscriptions
```graphql
type Subscription {
# Real-time updates
resourceUpdated(resourceId: ID!): Resource!
metricsUpdated(resourceId: ID!, metricType: MetricType!): MetricValue!
healthChanged(resourceId: ID!): HealthStatus!
findingCreated(controlId: ID): Finding!
riskCreated(resourceId: ID): Risk!
}
```
---
## Database Schema (PostgreSQL)
### Core Tables
```sql
-- Regions
CREATE TABLE regions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
code VARCHAR(50) UNIQUE NOT NULL,
country VARCHAR(100),
latitude DECIMAL(10, 8),
longitude DECIMAL(11, 8),
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
metadata JSONB
);
-- Resources (polymorphic)
CREATE TABLE resources (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
type VARCHAR(50) NOT NULL,
region_id UUID REFERENCES regions(id),
site_id UUID,
cluster_id UUID,
parent_id UUID REFERENCES resources(id),
provider VARCHAR(50),
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW(),
metadata JSONB
);
-- Resource relationships (graph edges)
CREATE TABLE resource_relationships (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
from_resource_id UUID NOT NULL REFERENCES resources(id),
to_resource_id UUID NOT NULL REFERENCES resources(id),
relationship_type VARCHAR(50) NOT NULL,
metadata JSONB,
created_at TIMESTAMP DEFAULT NOW(),
UNIQUE(from_resource_id, to_resource_id, relationship_type)
);
-- Metrics (time-series)
CREATE TABLE metrics (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
resource_id UUID NOT NULL REFERENCES resources(id),
metric_type VARCHAR(50) NOT NULL,
value DECIMAL(20, 4) NOT NULL,
timestamp TIMESTAMP NOT NULL,
labels JSONB,
PRIMARY KEY (resource_id, metric_type, timestamp)
);
-- Well-Architected Framework
CREATE TABLE pillars (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
code VARCHAR(50) UNIQUE NOT NULL,
name VARCHAR(255) NOT NULL,
description TEXT
);
CREATE TABLE controls (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
pillar_id UUID NOT NULL REFERENCES pillars(id),
code VARCHAR(50) NOT NULL,
name VARCHAR(255) NOT NULL,
description TEXT,
UNIQUE(pillar_id, code)
);
CREATE TABLE findings (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
control_id UUID NOT NULL REFERENCES controls(id),
resource_id UUID NOT NULL REFERENCES resources(id),
status VARCHAR(50) NOT NULL,
severity VARCHAR(50) NOT NULL,
title VARCHAR(255) NOT NULL,
description TEXT,
recommendation TEXT,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- Indexes for performance
CREATE INDEX idx_resources_type ON resources(type);
CREATE INDEX idx_resources_region ON resources(region_id);
CREATE INDEX idx_metrics_resource_time ON metrics(resource_id, timestamp DESC);
CREATE INDEX idx_findings_resource ON findings(resource_id);
CREATE INDEX idx_findings_control ON findings(control_id);
```
---
## Neo4j Graph Schema (Optional)
For complex graph queries, Neo4j can be used:
```cypher
// Node labels
(:Region)
(:Site)
(:Cluster)
(:Node)
(:Service)
(:Network)
(:Storage)
// Relationships
(:Region)-[:CONTAINS]->(:Site)
(:Site)-[:CONTAINS]->(:Cluster)
(:Cluster)-[:CONTAINS]->(:Node)
(:Service)-[:DEPENDS_ON]->(:Service)
(:Network)-[:CONNECTS_TO]->(:Network)
(:Resource)-[:AFFECTS_PILLAR]->(:Pillar)
```
---
## Integration Points
### Control Plane Adapters
The data model integrates with:
1. **Proxmox**: Cluster, VM, storage data
2. **Kubernetes/Crossplane**: Pod, service, network data
3. **Cloudflare**: Tunnel, DNS, network data
4. **Prometheus**: Metrics and telemetry
5. **Custom APIs**: Additional infrastructure sources
### Normalization
All control plane data is normalized into the unified graph model, allowing:
* Single source of truth
* Consistent query interface
* Cross-platform relationships
* Unified visualization
---
## Future Enhancements
1. **AI/ML Integration**: Model predictions and recommendations
2. **Cost Optimization**: Cost tracking and optimization recommendations
3. **Security Posture**: Security assessments and threat intelligence
4. **Compliance**: Compliance tracking and reporting
5. **Cultural Intelligence**: Enhanced cultural context and adaptation