Sankofa/docs/architecture/tech-stack.md

# Sankofa Phoenix: Technology Stack

## Overview

**Sankofa Phoenix** is built on a modern, scalable technology stack designed for:

* **Dashboards** → fast, reactive, drill-down, cross-filtering
* **Drag-n-drop & node graph editing** → workflows, network topologies, app maps
* **3D visualizations** → network and architecture in 3D, interactive camera, labels, layers
* **"Studio quality" visuals** → film/AAA-game-adjacent look, not BI chart boilerplate
* **Future-proof** → typed, testable, driven by existing control plane (Proxmox, Crossplane, Cloudflare, etc.)

---

## Front-End Stack

### Core Framework

**Next.js 14+ (React + TypeScript)**
- App Router for modern routing
- SSR/ISR for performance and SEO
- API routes for light backend glue
- Excellent DX, file-based routing, easy deployment

### Language

**TypeScript**
- Strong typing for complex graph interactions
- Type safety for 3D scenes and data structures
- Better IDE support and developer experience

### Styling & Layout

**TailwindCSS + shadcn/ui**
- Modern, dark-mode-friendly design system
- Dense "studio dashboard" aesthetic
- Full control over styling and theming
- Component-based UI library

**Framer Motion**
- Smooth animations and transitions
- Panel transitions, node selection, drag-n-drop feedback
- Mode transitions (2D <-> 3D)

### State Management

**Zustand / Jotai**
- Local UI state management
- Lightweight and performant

**React Query (TanStack Query)**
- Server state management
- GraphQL client integration
- Caching and synchronization

---

## Dashboards & Analytics

### Charts / Dashboards

**ECharts** (via React wrappers)
- Complex, animated dashboards
- High performance
- Extensive customization options
- Studio-quality visuals

**Alternative: visx / Recharts**
- More React-native feel
- Good for design-system-driven visuals

### Tables & Data Grids

**TanStack Table (React Table)**
- Advanced, virtualized tables
- Custom cell renders (status pills, spark-lines, tags)
- Excellent performance for large datasets

### Maps / Geo

**Mapbox GL JS** or **deck.gl**
- Plotting regions, edge locations, tunnel endpoints
- Interactive geographic visualizations

---

## Drag-n-Drop and Visual Editors

### Graph/Node-Based Editing

**React Flow**
- Excellent for node/edge editors
- Built-in zoom/pan, minimap
- Custom node/edge renderers
- Perfect for L2 "Well-Architected Framework" diagrams
- Logical views of architecture

### General Drag-n-Drop

**@dnd-kit** or **react-beautiful-dnd**
- List/board/kitchen-sink DnD
- Building component palettes
- Dashboard layout editors

### Canvas 2D

**Konva.js / react-konva**
- Highly interactive 2D diagrams
- Annotations and overlays
- High-performance 2D rendering

**Pattern:**
- L2 / logical diagrams → React Flow / Konva
- L3 / detailed visuals → 3D WebGL (see 3D section)

---

## 3D Visualizations

### 3D Engine

**three.js**
- WebGL engine for 3D graphics
- Industry standard for web 3D

**react-three-fiber (R3F)**
- Declarative three.js in React
- Component-based 3D scene management

**@react-three/drei**
- Camera controls, orbits, gizmos
- Text rendering, environment setup
- Helper components for common 3D patterns

**postprocessing** (R3F plugin)
- Bloom effects
- SSAO (Screen-Space Ambient Occlusion)
- Depth of field
- Color grading
- Cinematic visual quality

### Graph & Network Visuals in 3D

**3D Graph Layout**
- **d3-force-3d** or **ngraph.forcelayout3d**
- Position nodes in 3D space
- Feed positions into R3F meshes (spheres, cubes, capsules)
- Connect with lines or tubes

**Topologies**
- Each **node** = service, region, cluster, VPC, etc.
- Each **edge** = peering, VPN, Cloudflare tunnel, dependency
- Layers for:
  * Regions (325 global nodes)
  * Availability zones / sites
  * Services running
  * Health & risk overlays (color, size, pulsing)

**Interactions**
- Orbital camera (drei's `<OrbitControls />`)
- Click nodes → open side panel with metrics
- Hover edges → show latency, bandwidth, status
- Use **instanced meshes** for performance with many nodes

---

## Back-End & Data Model

### API Layer

**GraphQL**
- **Option A**: Hasura on Postgres (auto GraphQL)
- **Option B**: Apollo Server / NestJS GraphQL over Postgres/Neo4j
- Perfect fit for graph-like data:
  * regions
  * clusters
  * networks
  * services
  * dependencies

### Data Store

**Relational + Graph Hybrid**

**Option A (Pragmatic):**
- **PostgreSQL** with:
  * Topology tables (resources, relations, metrics)
  * JSONB for flexible metadata
  * Materialized views for dashboards

**Option B (More "Native"):**
- **Neo4j** or another graph DB for relationships
  * Natural for queries like:
    * "Show all paths from this service to this edge"
    * "Which nodes share a risk factor?"

**Hybrid Approach:**
- Start with Postgres
- Move hot graph queries to Neo4j later
- Best of both worlds

### Real-Time

**Real-Time Pipeline**
- **Metrics**: Prometheus → push to TSDB (Prometheus / Timescale)
- **Events**: Kafka/Redpanda or NATS for events (state changes, incidents)
- **UI**: WebSockets / GraphQL Subscriptions to push updates

**Examples:**
- Node changes color when health crosses threshold
- Edge animates when traffic spikes
- New region lights up when provisioned via Crossplane

---

## Integration with Infrastructure

### Control-Plane Adapters (Backend Services)

Services that:
- Call **Proxmox APIs** (cluster, VM, storage)
- Call **Cloudflare APIs** (tunnels, Zero Trust configs, DNS)
- Query **Crossplane/Kubernetes** (CRDs representing resources)

### Normalize into "Resource Graph"

Everything becomes a node in graph DB or Postgres schema:
- Region
- Site
- Cluster
- Node
- VM/Pod/Service
- Tunnel
- Policy

**UI reads this graph, not raw cloud APIs.**

This enables Azure-Graph-like behavior without Azure.

---

## Tooling, DevOps, and Quality

### Dev Environment

- **Package Manager**: pnpm / yarn
- **Linting**: ESLint
- **Formatting**: Prettier
- **Component Development**: Storybook (for UI components & visual system)
- **Testing**: Vitest / Jest + React Testing Library

### Build & Deploy

**Docker Images** for:
- Front-end (Next.js)
- API (GraphQL servers)
- Graph DB / Postgres

**Deploy on:**
- Kubernetes control cluster (part of architecture)
- Traefik or NGINX Ingress behind Cloudflare

### Observability

- **Logs**: Loki / ELK
- **Metrics**: Prometheus + Grafana
- **Traces**: OpenTelemetry / Tempo

---

## Well-Architected Framework Visualizations

### Pillar Views

- Security
- Reliability
- Cost Optimization
- Performance Efficiency
- Operational Excellence
- Sustainability

### Layered Views

- **Physical** (Proxmox nodes, racks)
- **Network** (subnets, tunnels, regions)
- **Application** (services, workloads, dependencies)
- **Governance** (policies, SLAs, compliance)

### Implementation Pattern

1. **Model pillars & controls in backend**
   - GraphQL types: Pillar, Control, Finding, Risk, Recommendation

2. **Bind each resource node** to:
   - Which pillar(s) it affects
   - Score/health for each pillar

3. **In UI:**
   - Use **React Flow** 2D diagrams for pillar-specific overlays
   - Use **R3F 3D** to show structural/physical layout, colored by pillar health
   - Provide **"Lens" switch** (Performance lens, Security lens, Cost lens) that:
     * Changes color mapping & overlays
     * Toggles visibility of certain node types
     * Animates transitions with Framer Motion / R3F

This delivers **studio-quality, cinematic, but cognitively useful** Well-Architected views.

---

## Recommended Stack Summary (Opinionated)

### Front-End

* Next.js (React, TypeScript)
* TailwindCSS + shadcn/ui
* React Query / Apollo Client
* Framer Motion
* React Flow + @dnd-kit
* react-three-fiber + drei + postprocessing
* ECharts / visx for charts
* TanStack Table for data grids

### Back-End

* GraphQL API (NestJS + Apollo OR Hasura + Postgres)
* Postgres (core data) + optional Neo4j for complex graph queries
* WebSockets / GraphQL Subscriptions for real-time

### Infra

* K8s on existing clusters
* Traefik/NGINX ingress behind Cloudflare
* Prometheus, Loki, Grafana, OpenTelemetry

---

## Next Steps

1. Design the **actual data model** (tables/graph schema)
2. Sketch the **component structure** of the UI (pages, editors, 3D views)
3. Write **starter Next.js project structure** with key libraries wired together