Sankofa/docs/architecture/well-architected.md

Sankofa Phoenix: Well-Architected Framework Visualization

Overview

Sankofa Phoenix implements a comprehensive Well-Architected Framework (WAF) visualization system that provides:

• Studio-quality visuals with cinematic aesthetics
• Multi-layered views of the same architecture
• Pillar-specific lenses for focused analysis
• Interactive 3D and 2D visualizations
• Real-time health and risk overlays

---

Well-Architected Framework Pillars

1. Security

Focus: Protecting information, systems, and assets

Key Areas:

• Identity and access management
• Threat detection and response
• Data protection
• Infrastructure security
• Compliance and governance

Visual Indicators:

• Color: Red/Amber for risks, Green for secure
• Icons: Shield, lock, key symbols
• Overlays: Security zones, access boundaries

2. Reliability

Focus: Ability to recover from failures and meet demand

Key Areas:

• Fault tolerance
• Disaster recovery
• High availability
• Capacity planning
• Change management

Visual Indicators:

• Color: Green for healthy, Red for failures
• Icons: Checkmark, warning, error symbols
• Overlays: Availability zones, redundancy paths

3. Cost Optimization

Focus: Achieving the lowest price point

Key Areas:

• Right-sizing resources
• Reserved capacity
• Cost monitoring
• Eliminating waste
• Pricing models

Visual Indicators:

• Color: Green for optimized, Red for high cost
• Icons: Dollar, chart, trend symbols
• Overlays: Cost heatmaps, spending trends

4. Performance Efficiency

Focus: Using computing resources efficiently

Key Areas:

• Compute optimization
• Storage optimization
• Network optimization
• Database optimization
• Caching strategies

Visual Indicators:

• Color: Green for efficient, Red for bottlenecks
• Icons: Speed, performance, optimization symbols
• Overlays: Performance metrics, bottlenecks

5. Operational Excellence

Focus: Running and monitoring systems

Key Areas:

• Automation
• Change management
• Monitoring and observability
• Incident response
• Documentation

Visual Indicators:

• Color: Blue for operational, Amber for issues
• Icons: Gear, monitor, alert symbols
• Overlays: Operational status, automation flows

6. Sustainability

Focus: Environmental impact and efficiency

Key Areas:

• Energy efficiency
• Resource optimization
• Carbon footprint
• Renewable energy
• Waste reduction

Visual Indicators:

• Color: Green for sustainable, Red for impact
• Icons: Leaf, energy, environment symbols
• Overlays: Energy consumption, carbon footprint

---

Visualization Architecture

Layered Views

The same infrastructure can be viewed through different layers:

1. Physical Layer

• Shows: Proxmox nodes, racks, physical infrastructure
• Use Case: Physical topology, hardware health
• Visualization: 3D physical layout, node positions

2. Network Layer

• Shows: Subnets, tunnels, regions, network connections
• Use Case: Network topology, connectivity, routing
• Visualization: 3D network graph, connection flows

3. Application Layer

• Shows: Services, workloads, dependencies
• Use Case: Application architecture, service dependencies
• Visualization: 2D/3D service graph, dependency trees

4. Governance Layer

• Shows: Policies, SLAs, compliance, access controls
• Use Case: Governance, compliance, policy enforcement
• Visualization: Policy overlays, compliance status

---

Implementation Pattern

Backend Model

# Pillar definition
type Pillar {
  id: ID!
  code: PillarCode!
  name: String!
  controls: [Control!]!
}

# Control definition
type Control {
  id: ID!
  pillar: Pillar!
  code: String!
  name: String!
  findings: [Finding!]!
}

# Finding for a resource
type Finding {
  id: ID!
  control: Control!
  resource: Resource!
  status: FindingStatus!
  severity: Severity!
  recommendation: String
}

# Risk associated with resource
type Risk {
  id: ID!
  resource: Resource!
  pillar: Pillar
  severity: Severity!
  title: String!
  mitigation: String
}

Resource Binding

Each resource node is bound to:

1. Pillar Affiliations: Which pillars affect this resource
2. Health Scores: Score (0-100) for each pillar
3. Findings: Specific findings for this resource
4. Risks: Risks associated with this resource

UI Implementation

2D Diagrams (React Flow)

Pillar-Specific Overlays:

• Security lens: Show security zones, access boundaries
• Reliability lens: Show redundancy, failover paths
• Cost lens: Show cost heatmaps, spending trends
• Performance lens: Show bottlenecks, optimization opportunities
• Operations lens: Show automation, monitoring coverage
• Sustainability lens: Show energy consumption, carbon footprint

Features:

• Custom node renderers based on pillar health
• Color coding by pillar score
• Overlay toggles for different aspects
• Interactive drill-down

3D Visualizations (react-three-fiber)

Structural/Physical Layout:

• 3D representation of infrastructure
• Nodes colored by pillar health
• Edges showing relationships
• Layers for different resource types

Pillar Lenses:

• Switch between pillar views
• Color mapping changes based on selected pillar
• Node size/glow based on health score
• Animated transitions between lenses

Features:

• Orbital camera controls
• Click nodes for details
• Hover for quick info
• Layer visibility toggles
• Smooth animations

---

Lens Switching System

Lens Types

1. Security Lens

   • Color: Red/Amber/Green based on security posture
   • Overlays: Security zones, access boundaries, threat indicators
   • Filters: Show only security-relevant resources

2. Reliability Lens

   • Color: Green/Amber/Red based on availability
   • Overlays: Redundancy paths, failover capabilities
   • Filters: Show reliability-critical resources

3. Cost Lens

   • Color: Green/Amber/Red based on cost efficiency
   • Overlays: Cost heatmaps, spending trends
   • Filters: Show high-cost resources

4. Performance Lens

   • Color: Green/Amber/Red based on performance
   • Overlays: Bottlenecks, optimization opportunities
   • Filters: Show performance-critical resources

5. Operations Lens

   • Color: Blue/Amber based on operational status
   • Overlays: Automation coverage, monitoring
   • Filters: Show operational resources

6. Sustainability Lens

   • Color: Green/Amber/Red based on environmental impact
   • Overlays: Energy consumption, carbon footprint
   • Filters: Show high-impact resources

Lens Switching UI

// Lens selector component
<LensSelector
  currentLens={selectedLens}
  onLensChange={handleLensChange}
  pillars={pillars}
/>

// Animated transition
<AnimatePresence mode="wait">
  <motion.div
    key={selectedLens}
    initial={{ opacity: 0 }}
    animate={{ opacity: 1 }}
    exit={{ opacity: 0 }}
  >
    <Visualization lens={selectedLens} />
  </motion.div>
</AnimatePresence>

---

Visual Design Principles

Studio Quality Aesthetic

• Dark Theme: Near-black backgrounds (#0A0A0A)
• Neon Accents: Teal, magenta, cyan, amber for status
• Glow Effects: Subtle glow around important nodes
• Layered Depth: Multiple layers for visual hierarchy
• Smooth Animations: 200-300ms transitions

Color Coding

Health Scores:

• 90-100: Bright Green (#00FF88)
• 70-89: Amber (#FFB800)
• 50-69: Orange (#FF8C00)
• 0-49: Red (#FF0040)

Pillar-Specific:

• Security: Red spectrum
• Reliability: Green spectrum
• Cost: Blue spectrum
• Performance: Cyan spectrum
• Operations: Purple spectrum
• Sustainability: Green spectrum

Typography

• Headings: Inter/Satoshi, bold
• Metrics: Monospace for numbers
• Labels: Inter, regular
• Consistent Scale: 12px, 14px, 16px, 18px, 24px, 32px, 48px

---

Interactive Features

Node Interactions

1. Click: Open side panel with:

   • Resource details
   • Pillar scores
   • Findings and risks
   • Recommendations
   • Metrics

2. Hover: Show tooltip with:

   • Resource name
   • Health score
   • Quick metrics
   • Status

3. Select: Highlight and show:

   • Related resources
   • Dependencies
   • Affected pillars

Edge Interactions

1. Hover: Show:

   • Connection type
   • Latency
   • Bandwidth
   • Status

2. Click: Show:

   • Connection details
   • Metrics
   • Health

View Controls

1. Zoom/Pan: Navigate the visualization
2. Filter: Show/hide resource types
3. Search: Find specific resources
4. Time Range: View historical states
5. Export: Export visualization as image/PDF

---

Real-Time Updates

WebSocket Subscriptions

subscription {
  healthChanged(resourceId: $resourceId) {
    resourceId
    healthStatus
    pillarScores
  }
  findingCreated(controlId: $controlId) {
    id
    resource
    status
    severity
  }
  riskCreated(resourceId: $resourceId) {
    id
    resource
    severity
    title
  }
}

Update Behavior

1. Node Color: Updates when health score changes
2. Node Size: Updates when metrics change
3. Edge Animation: Pulses when traffic spikes
4. Overlay Refresh: Updates when findings change
5. Smooth Transitions: Animated updates, not jarring

---

Component Structure

src/components/well-architected/
├── LensSelector.tsx          # Pillar lens selector
├── PillarView.tsx            # Pillar-specific view
├── ResourceNode.tsx          # Resource node component
├── FindingOverlay.tsx       # Findings overlay
├── RiskIndicator.tsx        # Risk indicators
├── HealthScore.tsx          # Health score display
├── WAFDashboard.tsx         # Main WAF dashboard
├── WAF3DView.tsx            # 3D WAF visualization
└── WAF2DView.tsx            # 2D WAF visualization

---

Future Enhancements

1. AI Recommendations: ML-powered optimization suggestions
2. Predictive Analytics: Forecast future issues
3. Automated Remediation: Auto-fix common issues
4. Custom Pillars: User-defined assessment pillars
5. Compliance Mapping: Map to specific compliance frameworks
6. Cost Forecasting: Predict future costs
7. Sustainability Metrics: Enhanced environmental tracking

---

Best Practices

1. Start with Overview: Show high-level health across all pillars
2. Drill Down Gradually: Allow users to explore details
3. Provide Context: Always show what pillar/lens is active
4. Make Actions Clear: Show what can be done with findings
5. Prioritize: Highlight critical issues first
6. Keep It Visual: Use visuals over text when possible
7. Enable Comparison: Compare resources side-by-side
8. Track Progress: Show improvement over time