furt/devdocs/furt_master_strategy.md

# Furt: Master-Strategie & Technologie-Migration

**Erstellt:** 17. Juni 2025  
**Letzte Aktualisierung:** 17. Juni 2025  
**Version:** 1.0  
**Verantwortlich:** DAW-Team  
**Dateipfad:** devdocs/MASTER_STRATEGY.md

## Zweck dieses Dokuments

Dieses Dokument definiert die langfristige Technologie-Migrationsstrategie für das gesamte Dragons@Work Ökosystem, mit Furt als erstem Schritt zur vollständigen digitalen Souveränität.

## 🎯 Gesamtvision: Komplette Tech-Souveränität

### Ausgangssituation (Juni 2025)
- **Server:** Ubuntu + Apache + ISPConfig
- **Website:** Hugo + digitalindependent Theme
- **Planned API:** Go-basiertes Furt (noch nicht implementiert)
- **Dependencies:** Viele Corporate-controlled Tools

### Zielsituation (18-24 Monate)
- **Server:** OpenBSD + httpd + eigene Scripts
- **Website:** vefari (eigener Generator) + eigenes Theme
- **API:** C + Lua Furt (vollständig souverän)
- **Dependencies:** Minimal, alle selbst-kontrolliert

## 📋 Migration-Roadmap

### Phase 1: Furt API-Grundlagen (4 Wochen)
**Woche 1: Mail-Service (Pure Lua)**
- [x] Entscheidung: Pure Lua statt Go
- [ ] HTTP-Server (lua-socket)
- [ ] Mail-Handler (SMTP zu Postfix)
- [ ] API-Key-Auth
- [ ] Hugo-Integration (POST-based)

**Woche 2-3: Service-Expansion**
- [ ] Comment-Service (sagjan-Integration)
- [ ] Health-Checks
- [ ] Error-Handling
- [ ] Basic Logging

**Woche 4: Production-Ready**
- [ ] HTTPS (Lua-SSL)
- [ ] Systemd-Integration  
- [ ] Monitoring
- [ ] Documentation

### Phase 2: C-Integration (4-6 Wochen)
**Performance-Layer:**
- [ ] C-HTTP-Server (< 500 Zeilen)
- [ ] C ↔ Lua Bridge
- [ ] Memory-Management
- [ ] Security-Hardening

### Phase 3: Infrastructure-Migration (6-12 Monate)
**Server-Migration:**
- [ ] OpenBSD-Evaluation
- [ ] ISPConfig → eigene Scripts
- [ ] Apache → OpenBSD httpd
- [ ] SSL-Management ohne Corporate-Tools

### Phase 4: Website-Migration (3-6 Monate parallel)
**vefari-Entwicklung:**
- [ ] Hugo-Kompatibilität (Templates/Content)
- [ ] Markdown-Processing
- [ ] Multi-Language-Support
- [ ] Build-System

### Phase 5: Complete Independence (langfristig)
**Advanced Features:**
- [ ] Eigener Browser (Exploration)
- [ ] Föderation zwischen Furt-Instanzen
- [ ] Advanced Services (Shop, Calendar, etc.)

## 🏗️ Architektur-Prinzipien

### Modularität (Anti-Monolith)
```
Jedes Script/Modul: < 200 Zeilen
Jede Funktion: < 50 Zeilen
Jede Datei: Ein klarer Zweck
Keine 800-Zeilen-Monster!
```

### Technologie-Auswahl nach Tech-Reference
✅ **Erlaubt (Souverän):**
- C + GCC/musl
- Lua (PUC-Rio University)
- LMDB (Howard Chu/Symas)
- OpenBSD httpd

❌ **Vermeiden (Corporate-Controlled):**
- Go (Google)
- Node.js (Corporate-Oligopol)
- Apache (Corporate-finanziert)
- MariaDB (VC-finanziert)

⚠️ **Temporary OK (Migration-Pfad):**
- Ubuntu (→ OpenBSD)
- Apache (→ OpenBSD httpd)

### Development-Prinzipien
1. **Verstehbarkeit** vor Features
2. **Kleine Module** vor Monolithen
3. **Eigene Kontrolle** vor Convenience
4. **Langfristig stabil** vor "Modern"
5. **Testing** für alles

## 🔧 Technical Implementation Strategy

### Furt-Architecture (Final)
```
┌─────────────────┐
│ OpenBSD httpd   │ (SSL-Terminierung)
│ (Port 443)      │
└─────────┬───────┘
          │
┌─────────▼───────┐
│ C-HTTP-Gateway  │ (Routing, Auth)
│ (Port 8080)     │
└─────────┬───────┘
          │
    ┌─────▼─────┐ ┌─────────┐ ┌─────────┐
    │ Lua-Mail  │ │Lua-Comm│ │Lua-Shop │
    │(Port 8081)│ │(8082)   │ │(8083)   │
    └───────────┘ └─────────┘ └─────────┘
```

### Service-Pattern (Standardisiert)
```lua
-- services/template.lua
local service = {
    name = "service_name",
    port = 808X,
    
    -- Standard Interface
    handle_request = function(self, request)
        -- Input-Validation (< 20 Zeilen)
        -- Business-Logic (< 50 Zeilen) 
        -- Response-Formatting (< 10 Zeilen)
    end,
    
    health_check = function(self)
        -- Health-Logic (< 10 Zeilen)
    end
}
```

### Testing-Strategy
```
tests/
├── unit/              # Lua-Modul-Tests
│   ├── test_mail.lua
│   └── test_auth.lua
├── integration/       # Service-Tests
│   └── test_api.lua
├── system/           # End-to-End-Tests
│   └── test_hugo.lua
└── performance/      # Load-Tests
    └── test_load.lua
```

## 📊 SMTP-Configuration (Week 1)

### Postfix-Integration
```lua
-- config/mail.lua
return {
    smtp = {
        server = "mail.dragons-at-work.de",
        port = 465,
        username = os.getenv("MAIL_USERNAME"), -- xxxx@dragons-at-work.de
        password = os.getenv("MAIL_PASSWORD"),
        security = "ssl/tls",
        from = "noreply@dragons-at-work.de",
        to = "michael@dragons-at-work.de"
    }
}
```

### Security-Pattern
```lua
-- Nie Passwörter in Code!
-- Environment-Variables für Secrets
-- API-Keys in LMDB
-- IP-Allowlisting für Hugo
```

## 🚀 Hugo-Integration (Week 1)

### Shortcode-Pattern
```hugo
{{< furt-mail
    api-endpoint="https://api.dragons-at-work.de/v1/mail/send"
    api-key="hugo-frontend-key"
    success-url="/contact/thanks/"
>}}
```

### Progressive Enhancement
```html
<!-- Form funktioniert ohne JavaScript -->
<form method="POST" action="/v1/mail/send">
    <input name="name" required>
    <input name="email" type="email" required>
    <textarea name="message" required></textarea>
    <button type="submit">Senden</button>
</form>

<!-- JavaScript für UX-Enhancement -->
<script>
// AJAX-Submit, aber Fallback auf normale Form
</script>
```

## 📈 Success-Metrics

### Week 1 Success-Criteria
- [ ] HTTP-Request funktioniert
- [ ] Mail wird via SMTP gesendet
- [ ] API-Key-Auth schützt Endpoint
- [ ] Hugo-Form sendet erfolgreich
- [ ] < 100ms Response-Time
- [ ] Jedes Modul < 200 Zeilen

### Phase 1 Success-Criteria  
- [ ] Production-ready Mail-Service
- [ ] Comment-Service implementiert
- [ ] HTTPS mit Lua-SSL
- [ ] Systemd-Service läuft stabil
- [ ] Documentation komplett

### Long-term Success-Criteria
- [ ] Komplette Ubuntu → OpenBSD Migration
- [ ] Hugo → vefari Migration
- [ ] < 10 MB Total Memory für alle Services
- [ ] Zero Corporate-Dependencies

## 🔄 Migration-Safety

### Parallel-Betrieb-Strategie
```
Week 1-4: Lua-Furt || Apache (parallel)
Month 2-6: C+Lua-Furt || Apache (parallel)  
Month 6+: C+Lua-Furt || OpenBSD-httpd (parallel)
```

### Rollback-Plan
- Jede Migration-Phase kann rückgängig gemacht werden
- Hugo bleibt funktionsfähig während vefari-Entwicklung
- Apache bleibt als Fallback während OpenBSD-Migration

### Testing vor Production
- Alle Changes erst auf Testumgebung
- Graduelle Umstellung Service für Service
- Monitoring für Performance-Regression

## 📝 Documentation-Strategy

### Development-Docs
- [ ] **Installation-Guide** (Linux → OpenBSD)
- [ ] **API-Documentation** (OpenAPI-Style)
- [ ] **Service-Development-Guide** (Lua-Pattern)
- [ ] **Testing-Guide** (Unit + Integration)

### User-Docs
- [ ] **Hugo-Integration-Guide**
- [ ] **vefari-Migration-Guide**
- [ ] **Self-Hosting-Guide**

### Philosophy-Docs
- [ ] **Tech-Souveränität-Rationale**
- [ ] **Corporate-Capture-Analysis**
- [ ] **Long-term-Vision**

## 🎯 Next Session Preparation

### Session-Focus: Lua-HTTP-Server Start
1. **Lua-Dependencies** installieren
2. **Basic HTTP-Server** (50-100 Zeilen)
3. **Request-Parsing** (POST-Body, Headers)
4. **Response-Formatting** (JSON)
5. **Error-Handling** (Basic)

### Session-Deliverable
- `src/main.lua` - Funktionierender HTTP-Server
- `test/test_http.lua` - Basis-Tests
- `scripts/start.sh` - Start-Script

### Session-Success-Metric
- `curl -X POST http://localhost:8080/test` → HTTP 200 Response

---

**Diese Master-Strategie dient als Kompass für alle technischen Entscheidungen und stellt sicher, dass jeder kleine Schritt zum großen Ziel der technologischen Souveränität beiträgt.**