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

```graphql
# 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

```typescript
// 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

```graphql
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