docs/ARCHITECTURE_CLOUDBORNE.md

# 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*