Initial Phoenix Sankofa Cloud setup
- 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
This commit is contained in:
defiQUG
342
docs/architecture/tech-stack.md
Normal file
342
docs/architecture/tech-stack.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user