6f28146ac3
- Complete project structure with Next.js frontend - GraphQL API backend with Apollo Server - Portal application with NextAuth - Crossplane Proxmox provider - GitOps configurations - CI/CD pipelines - Testing infrastructure (Vitest, Jest, Go tests) - Error handling and monitoring - Security hardening - UI component library - Documentation
343 lines
8.2 KiB
Markdown
343 lines
8.2 KiB
Markdown
# Phoenix Sankofa Cloud: Technology Stack
|
|
|
|
## Overview
|
|
|
|
**Phoenix Sankofa Cloud** 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
|
|
|