# WidgeTDC Cloud Architecture ## "Operation Cloudborne" - Headless Ghost Deployment **Version:** 1.0 **Dato:** 2025-12-13 **Status:** PRODUCTION LIVE --- ## 1. Arkitektur Oversigt ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ WIDGETDC CLOUD ARCHITECTURE │ │ "Headless Ghost" Pattern │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────────────────┐ │ BRUGER/KLIENT │ │ (Browser/App) │ └────────┬─────────┘ │ HTTPS ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ FRONTEND LAYER │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │ │ VERCEL (CDN Edge) │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ │ │ React 19 + Vite + Tailwind CSS v4 │ │ │ │ │ │ ──────────────────────────────────────── │ │ │ │ │ │ • Matrix UI (Cyber Terminal) │ │ │ │ │ │ • Widget System (Modular Components) │ │ │ │ │ │ • Zustand State Management │ │ │ │ │ │ • PWA Support (Offline-capable) │ │ │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ URL: https://widge-tdc-matrix-frontend.vercel.app │ │ │ └────────────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────────┘ │ │ REST API + WebSocket │ (CORS: origin: '*') ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ BACKEND LAYER │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │ │ HUGGING FACE SPACES (Docker) │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ │ │ Node.js 20 + Express + TypeScript │ │ │ │ │ │ ──────────────────────────────────────── │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ MCP Engine │ │ Cognitive │ │ Agent │ │ │ │ │ │ │ │ (63 Tools) │ │ Layer │ │ Orchestrator│ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ HyperLog │ │ Ingestion │ │ Security │ │ │ │ │ │ │ │ (Events) │ │ Pipeline │ │ Layer │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ URL: https://kraft102-widgetdc-backend.hf.space │ │ │ │ Port: 7860 (HF Standard) │ │ │ └────────────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ DATA LAYER │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ REDIS CLOUD │ │ NEO4J AURADB │ │ NEON POSTGRES │ │ │ │ (EU-North-1) │ │ (Cloud) │ │ (Serverless) │ │ │ │ ─────────────── │ │ ─────────────── │ │ ─────────────── │ │ │ │ • Hot Cache │ │ • Knowledge │ │ • Vector Store │ │ │ │ • Session State │ │ Graph │ │ (pgvector) │ │ │ │ • Event Pub/Sub │ │ • 4274 Nodes │ │ • Prisma ORM │ │ │ │ • Real-time │ │ • 5252 Rels │ │ • Structured │ │ │ │ Messaging │ │ • Cypher Query │ │ Data │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ │ AI/LLM LAYER │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ GEMINI │ │ OPENAI │ │ ANTHROPIC │ │ DEEPSEEK │ │ │ │ PRO │ │ GPT-4 │ │ CLAUDE │ │ V3 │ │ │ │ ────────── │ │ ────────── │ │ ────────── │ │ ────────── │ │ │ │ Primary AI │ │ Fallback │ │ Analysis │ │ Code Gen │ │ │ │ Reasoning │ │ Provider │ │ Tasks │ │ Tasks │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 2. Komponent Detaljer ### 2.1 Frontend ("The Satellite") | Attribut | Værdi | |----------|-------| | **Platform** | Vercel Edge Network | | **Framework** | React 19 + Vite 5 | | **Styling** | Tailwind CSS v4 | | **State** | Zustand | | **URL** | `https://widge-tdc-matrix-frontend.vercel.app` | **Funktioner:** - Cyber Terminal UI med widget-baseret dashboard - Real-time data via REST/WebSocket - PWA-enabled (offline support) - Responsive design **Environment Variables:** ``` VITE_API_URL=https://kraft102-widgetdc-backend.hf.space VITE_WS_URL=wss://kraft102-widgetdc-backend.hf.space ``` --- ### 2.2 Backend ("The Ghost") | Attribut | Værdi | |----------|-------| | **Platform** | Hugging Face Spaces (Docker) | | **Runtime** | Node.js 20-slim | | **Framework** | Express.js + TypeScript | | **Port** | 7860 | | **URL** | `https://kraft102-widgetdc-backend.hf.space` | **Arkitektur Lag:** ``` apps/backend/src/ ├── mcp/ # Model Context Protocol │ ├── cognitive/ # AI Engines │ │ ├── UnifiedGraphRAG.ts │ │ ├── AutonomousTaskEngine.ts │ │ ├── HybridSearchEngine.ts │ │ ├── StateGraphRouter.ts │ │ └── AgentTeam.ts │ ├── autonomous/ # Self-directed Agents │ └── memory/ # Cognitive Memory Systems ├── platform/ # Infrastructure Adapters │ ├── embeddings/ # Vector Embeddings │ ├── vector/ # Vector Stores │ ├── events/ # Redis Event Bus │ └── graph/ # Neo4j Adapter ├── services/ # Business Logic │ ├── hyper-log.ts # Event Streaming │ ├── ingestion/ # Data Pipeline (20+ adapters) │ └── external/ # External Integrations └── routes/ # API Endpoints ``` **MCP Tools (63 registreret):** - `cma.*` - Context Memory Access - `srag.*` - Semantic RAG Queries - `autonomous.*` - Agent Operations - `vidensarkiv.*` - Knowledge Archive - `widgets.*` - Widget Control - `ingestion.*` - Data Ingestion - `docgen.*` - Document Generation --- ### 2.3 Data Layer #### Redis Cloud (Hot Data) | Attribut | Værdi | |----------|-------| | **Region** | EU-North-1 (Stockholm) | | **Host** | `redis-16522.crce175.eu-north-1-1.ec2.cloud.redislabs.com` | | **Port** | 16522 | | **Formål** | Cache, Sessions, Pub/Sub | #### Neo4j AuraDB (Knowledge Graph) | Attribut | Værdi | |----------|-------| | **Type** | Cloud Graph Database | | **URI** | `neo4j+s://054eff27.databases.neo4j.io` | | **Nodes** | 4,274 | | **Relationships** | 5,252 | | **Formål** | Knowledge Graph, Entity Relations | #### Neon PostgreSQL (Vector Store) | Attribut | Værdi | |----------|-------| | **Type** | Serverless Postgres | | **Region** | US-East-2 | | **Extensions** | pgvector | | **ORM** | Prisma | | **Formål** | Structured Data, Vector Search | --- ### 2.4 AI/LLM Providers | Provider | API Key Env | Anvendelse | |----------|-------------|------------| | Google Gemini | `GOOGLE_AI_API_KEY` | Primary reasoning | | OpenAI GPT-4 | `OPENAI_API_KEY` | Fallback, embeddings | | Anthropic Claude | `ANTHROPIC_API_KEY` | Analysis tasks | | DeepSeek V3 | `DEEPSEEK_API_KEY` | Code generation | --- ## 3. Dataflow ``` ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Browser │────▶│ Vercel │────▶│ HF Space│────▶│ DBs │ │ Request │ │ CDN │ │ Backend │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ MCP Router │ │ │ └──────┬──────┘ │ │ │ │ │ ┌───────────────┼───────────────┤ │ ▼ ▼ ▼ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ Cognitive │ │ Redis │ │ Neo4j │ │ │ Engine │ │ Cache │ │ Graph │ │ └───────────┘ └───────────┘ └───────────┘ │ │ │ ▼ │ ┌───────────┐ │ │ AI/LLM │ │ │ Providers │ │ └───────────┘ │ │ ◀───────────────┘ Response ``` --- ## 4. API Endpoints ### Health & Status ``` GET /health # System health GET /api/hyper/status # HyperLog status GET /api/evolution/graph/stats # Graph statistics ``` ### MCP Protocol ``` GET /api/mcp/tools # List all tools (63) POST /api/mcp/route # Execute MCP tool WS /mcp/ws # WebSocket connection ``` ### Agent Operations ``` POST /api/team/delegate # Delegate task to agent GET /api/team/tasks # List agent tasks POST /api/team/plan # Create execution plan GET /api/team/status # Agent team status ``` ### Knowledge & Search ``` POST /api/srag/query # Semantic RAG search GET /api/knowledge/* # Knowledge endpoints POST /api/vidensarkiv/search # Archive search ``` --- ## 5. Environment Secrets (HF Spaces) | Secret | Status | Formål | |--------|--------|--------| | `DATABASE_URL` | ✅ | Neon PostgreSQL connection | | `NEO4J_URI` | ✅ | AuraDB endpoint | | `NEO4J_USER` | ✅ | AuraDB username | | `NEO4J_PASSWORD` | ✅ | AuraDB password | | `REDIS_URL` | ✅ | Redis Cloud connection | | `GOOGLE_AI_API_KEY` | ✅ | Gemini API | | `OPENAI_API_KEY` | ✅ | OpenAI API | | `ANTHROPIC_API_KEY` | ✅ | Claude API | | `JWT_SECRET` | ✅ | Auth tokens | --- ## 6. Deployment Pipeline ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ GitHub │────▶│ Build │────▶│ Deploy │ │ Push │ │ (Docker) │ │ (HF/Vercel)│ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────┐ │ Branch: hf-minimal │ │ ─────────────────── │ │ • Backend → push to 'hf' remote → HF Spaces │ │ • Frontend → auto-deploy from GitHub → Vercel │ └─────────────────────────────────────────────────────┘ ``` ### Deploy Commands ```bash # Backend til HF Spaces git push hf hf-minimal:main # Frontend til Vercel (auto via GitHub) git push origin hf-minimal ``` --- ## 7. Sikkerhed ### CORS Configuration ```typescript app.use(cors({ origin: '*', // Åben for alle origins (kan strammes) methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'], allowedHeaders: ['Content-Type', 'Authorization'] })); ``` ### Authentication - JWT-baseret authentication - Bearer tokens via `Authorization` header - Secret: `JWT_SECRET` environment variable ### GDPR Compliance - Data minimization i audit logs - Kun IDs/metadata logges - Retention policies implementeret --- ## 8. Monitorering ### Health Checks ```bash # Backend health curl https://kraft102-widgetdc-backend.hf.space/health # Graph stats curl https://kraft102-widgetdc-backend.hf.space/api/evolution/graph/stats # MCP tools count curl https://kraft102-widgetdc-backend.hf.space/api/mcp/tools ``` ### HF Spaces Docker Health ```dockerfile HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \ CMD node -e "require('http').get('http://localhost:7860/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))" ``` --- ## 9. Live URLs | Komponent | URL | Status | |-----------|-----|--------| | Frontend | https://widge-tdc-matrix-frontend.vercel.app | ✅ LIVE | | Backend | https://kraft102-widgetdc-backend.hf.space | ✅ LIVE | | Health | https://kraft102-widgetdc-backend.hf.space/health | ✅ OK | | API Docs | https://kraft102-widgetdc-backend.hf.space/api/mcp/tools | ✅ 63 tools | --- ## 10. Teknologi Stack Oversigt ``` ┌────────────────────────────────────────────────────────────┐ │ WIDGETDC TECH STACK │ ├────────────────────────────────────────────────────────────┤ │ FRONTEND │ React 19, Vite 5, Tailwind v4, Zustand │ │ BACKEND │ Node.js 20, Express, TypeScript 5.8 │ │ DATABASES │ PostgreSQL+pgvector, Neo4j 5, Redis 7 │ │ AI/LLM │ Gemini, OpenAI, Claude, DeepSeek │ │ HOSTING │ Vercel (FE), Hugging Face Spaces (BE) │ │ PROTOCOL │ MCP (Model Context Protocol) │ │ ARCHITECTURE │ Microservices, Event-Driven │ └────────────────────────────────────────────────────────────┘ ``` --- *Genereret: 2025-12-13* *Operation Cloudborne v1.0*