Sankofa/docs/architecture/data-model.md

# Sankofa Phoenix: Data Model & GraphQL Schema

## Overview

The data model for **Sankofa Phoenix** 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