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