docs: add complete cloud architecture documentation

- Full system architecture diagram (ASCII art)
- Component details for Frontend, Backend, Data Layer
- API endpoints documentation
- Environment secrets reference
- Deployment pipeline guide
- Tech stack overview

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/ARCHITECTURE_CLOUDBORNE.md

@@ -0,0 +1,400 @@
+# 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*