furt/devdocs/furt_konzept.md

Furt: API-Gateway im Einklang mit digitaler Souveränität

Erstellt: 03. Juni 2025
Letzte Aktualisierung: 03. Juni 2025
Version: 1.0
Verantwortlich: DAW-Team
Dateipfad: devdocs/KONZEPT.md

Zweck dieses Dokuments

Dieses Dokument definiert die grundlegenden Prinzipien, technischen Entscheidungen und Entwicklungsrichtlinien für das Furt API-Gateway-System. Es dient als zentrale Referenz für alle Entwickler und Mitwirkenden des Projekts.

Es richtet sich an Entwickler, Projektbeteiligte und alle, die am Code-Design und der Implementierung von Furt arbeiten.

Verwandte Dokumente

Dieses Dokument steht im Zusammenhang mit folgenden anderen Dokumenten:

• README.md: Öffentliche Projektbeschreibung, ../README.md
• ARCHITECTURE.md: Detaillierte Architekturübersicht, devdocs/ARCHITECTURE.md
• DECISIONS.md: Wichtige Architekturentscheidungen, devdocs/DECISIONS.md

1. Projektvision und Philosophie

Furt (germanisch für "Durchgang durch Wasser") ist ein selbst-gehostetes API-Gateway-System, das vollständig im Einklang mit den Prinzipien digitaler Souveränität, technologischer Angemessenheit und ressourcenschonender Entwicklung steht. Das System soll:

• Einfachheit über Komplexität stellen - leicht verständlich, wartbar und erweiterbar sein
• Ressourceneffizient arbeiten - minimale Server-Anforderungen und optimierte Performance
• Vollständige Kontrolle ermöglichen - transparenter Code ohne Black-Boxes
• Langfristig tragfähig sein - basierend auf bewährten Technologien
• Service-Modularität unterstützen - eigenständige Services unter einheitlicher API
• Mehrsprachigkeit von Anfang an unterstützen (DE, EN, FR)

Im Gegensatz zu existierenden Enterprise-Gateway-Lösungen fokussiert sich Furt auf:

• Native Installation als Hauptdeployment-Methode (keine Container-Abhängigkeit)
• Minimale externe Abhängigkeiten
• Transparente Konfiguration und Datenverarbeitung
• Volle Kompatibilität mit Low-Tech-Webseiten und statischen Site-Generatoren (besonders Hugo)
• Ein Gateway für alle Services - von Kontaktformularen bis zu komplexeren Anwendungen

2. Technische Architektur

2.1 Technology-Stack

• Backend: Go (für Performance, einfache Deployment durch einzelne Binärdatei)
• Gateway-Pattern: Reverse Proxy mit Service Registry
• Konfiguration: YAML-basiert (human-readable, versionierbar)
• Proxy-Integration: Apache als SSL-terminierender Reverse Proxy
• Services: Eigenständige Go-Binaries mit eigenen Ports
• Authentifizierung: API-Keys mit granularen Berechtigungen
• Logging: Strukturierte JSON-Logs mit konfigurierbaren Leveln

2.2 Projektstruktur

furt/
├── cmd/
│   ├── furt-gateway/              # Gateway-Binary
│   │   └── main.go
│   └── services/                  # Service-Binaries
│       ├── formular2mail/         # Kontaktformular → E-Mail
│       ├── sagjan/                # Kommentarsystem-Integration
│       └── shop/                  # Zukünftig: E-Commerce
├── internal/
│   ├── gateway/                   # Gateway-Kernlogik
│   │   ├── server.go              # HTTP-Server
│   │   ├── router.go              # Request-Routing
│   │   ├── proxy.go               # Service-Proxy
│   │   ├── auth.go                # Authentifizierung
│   │   └── middleware.go          # Gateway-Middleware
│   ├── services/                  # Service-Implementierungen
│   │   ├── formular2mail/         # Formular-Service-Logik
│   │   └── sagjan/                # Kommentar-Service-Logik
│   └── shared/                    # Geteilte Komponenten
│       ├── auth/                  # Authentifizierungs-Bibliothek
│       ├── config/                # Konfigurationsmanagement
│       └── logging/               # Strukturiertes Logging
├── configs/                       # Konfigurationsvorlagen
│   ├── gateway.yaml.example       # Gateway-Konfiguration
│   └── services/                  # Service-spezifische Configs
│       ├── formular2mail.yaml.example
│       └── sagjan.yaml.example
├── docs/                          # Öffentliche Dokumentation
│   ├── installation.md            # Installationsanleitung
│   ├── configuration.md           # Konfigurationsreferenz
│   ├── services/                  # Service-spezifische Dokumentation
│   └── api/                       # OpenAPI-Dokumentation
│       ├── gateway.yaml           # Gateway-API-Spec
│       └── services/              # Service-API-Specs
├── devdocs/                       # Entwicklerdokumentation
├── scripts/                       # Build & Deployment
│   ├── build-all.sh              # Alle Komponenten bauen
│   ├── deploy-gateway.sh         # Gateway deployment
│   ├── deploy-service.sh         # Service deployment
│   └── service-generator.sh      # Neuen Service scaffolden
├── examples/                      # Beispiel-Integrationen
│   ├── hugo/                     # Hugo-Shortcodes
│   ├── nginx/                    # Nginx-Proxy-Config
│   └── apache/                   # Apache-Proxy-Config
└── tests/                        # Test-Suites
    ├── integration/              # Service-Integration-Tests
    └── e2e/                      # End-to-End-Tests

2.3 Gateway-Architektur

Das Furt-Gateway implementiert ein Service-Registry-Pattern mit dateibasierter Konfiguration:

// Beispiel Gateway-Konfiguration
type GatewayConfig struct {
    Gateway  GatewaySettings         `yaml:"gateway"`
    Security SecurityConfig          `yaml:"security"`
    Services map[string]ServiceConfig `yaml:"services"`
    Logging  LoggingConfig           `yaml:"logging"`
}

type ServiceConfig struct {
    Enabled     bool          `yaml:"enabled"`
    PathPrefix  string        `yaml:"path_prefix"`     // /v1/mail, /v1/comments
    Upstream    string        `yaml:"upstream"`        // http://127.0.0.1:8081
    HealthCheck string        `yaml:"health_check"`    // /health
    Timeout     time.Duration `yaml:"timeout"`
    HasAdminUI  bool          `yaml:"has_admin_ui"`
    AdminPath   string        `yaml:"admin_path"`
}

Request-Flow:

1. Client → Apache (SSL-Terminierung) → Gateway
2. Gateway → Authentifizierung (API-Key + IP-Check)
3. Gateway → Service-Registry (Route Resolution)
4. Gateway → Service-Proxy (Request Forwarding)
5. Service → Response → Gateway → Client

3. Entwicklungsphasen gemäß natürlichem Wachstum

Die Entwicklung folgt einem natürlichen, organischen Prozess, der in vier Hauptphasen gegliedert ist:

3.1 Wurzelphase (Grundlagen)

• Ziel: Funktionierendes Gateway mit minimalen Features
• Schlüsselfeatures:
  • HTTP-Gateway mit grundlegendem Routing
  • API-Key-Authentifizierung mit IP-Beschränkungen
  • Formular2Mail-Service (E-Mail-Weiterleitung)
  • Basis-Hugo-Integration (Shortcodes)
  • Native Installationspakete für alle Komponenten

3.2 Wachstumsphase (Erweiterung)

• Ziel: Stabile, nutzbare Version mit wichtigen Services
• Schlüsselfeatures:
  • Sagjan-Integration (Kommentarsystem)
  • Erweiterte Middleware (Rate-Limiting, Logging)
  • Service-Generator für neue Services
  • Admin-Dashboard für Gateway-Management
  • Umfassende OpenAPI-Dokumentation

3.3 Blütephase (Vernetzung)

• Ziel: Verbesserung der Integration und Erweiterbarkeit
• Schlüsselfeatures:
  • Shop-Service (E-Commerce-Integration)
  • Webhook-Support für Service-Events
  • Erweiterte Monitoring-Funktionen
  • Multi-Tenant-Fähigkeiten
  • Service-Discovery-Verbesserungen

3.4 Fruchtphase (Reifung)

• Ziel: Langfristige Wartbarkeit und Community-Entwicklung
• Schlüsselfeatures:
  • Community-Service-Ecosystem
  • Performance-Optimierungen
  • High-Availability-Features
  • Föderation mit anderen Furt-Instanzen

4. Service-Integration-Konzept

4.1 Service-Entwicklung-Pattern

Jeder Service folgt einem standardisierten Muster:

// Service-Interface
type Service interface {
    // Für Gateway-Integration
    HandleRequest(w http.ResponseWriter, r *http.Request)
    HealthCheck() error
    
    // Für Standalone-Mode
    HandleWithAuth(w http.ResponseWriter, r *http.Request) // Eigene Auth
    
    // Service-Lifecycle
    Start(ctx context.Context) error
    Stop(ctx context.Context) error
}

// Service-Konfiguration
type ServiceConfig struct {
    Port        string            `yaml:"port"`
    Environment string            `yaml:"environment"`
    Auth        ServiceAuth       `yaml:"auth"`
    Logging     LoggingConfig     `yaml:"logging"`
    Custom      map[string]string `yaml:"custom"`  // Service-spezifisch
}

4.2 Dual-Mode-Operation

Jeder Service kann sowohl hinter dem Gateway als auch standalone betrieben werden:

Gateway-Mode:

• Service läuft auf localhost:PORT
• Authentifizierung erfolgt im Gateway
• Routing über Gateway-Pfade (/v1/mail, /v1/comments)

Standalone-Mode:

• Service läuft mit eigener Authentifizierung
• Direkte API-Endpunkte (/api/v1/mail/send)
• Eigene Dokumentation und Admin-UI

4.3 Service-Generator

Für schnelle Service-Entwicklung existiert ein Generator:

./scripts/service-generator.sh newsletter
# Erstellt:
# - cmd/services/newsletter/main.go
# - internal/services/newsletter/service.go
# - configs/services/newsletter.yaml
# - docs/services/newsletter.yaml
# - Deployment-Scripts

5. Implementierungsrichtlinien

5.1 Go-spezifische Standards

• Formatierung: gofmt für alle Go-Dateien verwenden
• Linting: golangci-lint mit angepasster Konfiguration
• Tests: Für jedes Package Testdateien (coverage-Ziel: mind. 80%)
• Abhängigkeiten: Minimale externe Abhängigkeiten, nur Go-Standard-Library + etablierte Packages
• Fehlerbehandlung: Explizite Fehlerprüfung, strukturierte Fehlerrückgaben
• Logging: Strukturiertes JSON-Logging mit verschiedenen Leveln
• Kommentare: Alle Funktionen und Typen auf Englisch dokumentieren

5.2 API-Design-Standards

• RESTful-Design: Standard HTTP-Methoden und Status-Codes
• Versionierung: /v1/ Pfad-Prefix für alle APIs
• JSON-Format: Einheitliche Request/Response-Strukturen
• Fehlerbehandlung: Konsistente Fehler-Response-Formate
• OpenAPI: Jeder Endpunkt wird dokumentiert

5.3 Konfigurationsmanagement

• YAML-Format: Human-readable, versionierbar
• Umgebungsvariablen: Für sensitive Daten (Tokens, Passwörter)
• Hierarchische Konfiguration: Default → Environment → Local
• Validierung: Konfiguration wird beim Start validiert

6. Qualitätssicherung

6.1 Teststrategie

• Unit-Tests: Für alle Kernfunktionen und Services
• Integration-Tests: Für Gateway ↔ Service-Kommunikation
• API-Tests: Für alle Endpunkte mit verschiedenen Authentifizierungsszenarien
• End-to-End-Tests: Für vollständige User-Journeys (Hugo → Gateway → Service)
• Performance-Tests: Load-Testing für Gateway und Services

6.2 Code-Review-Prozess

• Peer-Reviews für alle Änderungen
• Prüfung auf Einhaltung der Low-Tech-Prinzipien
• Überprüfung der API-Dokumentation
• Fokus auf Sicherheit und Performance
• Beachtung der Service-Integration-Patterns

6.3 Sicherheits-Standards

• API-Key-Management: Sichere Generation und Rotation
• Input-Validierung: Alle User-Inputs validieren
• Rate-Limiting: Schutz vor Abuse
• IP-Allowlisting: Restriktive Service-Zugriffe
• Secure Headers: Standard-Security-Headers
• Audit-Logging: Sicherheitsrelevante Events loggen

7. Deployment und Installation

7.1 Native Installation (primär)

Gateway-Deployment:

# Build
./scripts/build-all.sh

# Deploy Gateway
./scripts/deploy-gateway.sh

# Deploy Services
./scripts/deploy-service.sh formular2mail
./scripts/deploy-service.sh sagjan

Systemd-Integration:

• Gateway als furt-gateway.service
• Services als formular2mail-service.service, etc.
• Automatischer Start und Restart
• Structured Logging zu journald

7.2 Apache-Integration

Reverse-Proxy-Konfiguration:

<VirtualHost *:443>
    ServerName api.dragons-at-work.de
    
    # SSL-Terminierung durch Apache
    SSLEngine on
    SSLCertificateFile /path/to/cert.pem
    SSLCertificateKeyFile /path/to/key.pem
    
    # Gateway-Proxy
    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
    
    # Headers für Gateway
    ProxyPassReverse / http://127.0.0.1:8080/
    ProxySetHeader X-Forwarded-For %{REMOTE_ADDR}s
    ProxySetHeader X-Forwarded-Proto https
</VirtualHost>

7.3 Monitoring und Logging

Log-Struktur:

/var/log/furt/
├── gateway.log          # Gateway-Logs
├── formular2mail.log    # Service-Logs
├── sagjan.log
└── access.log           # Request-Logs

Health-Checks:

• Gateway: /health (Service-Status-Aggregation)
• Services: /health (Individual Service Health)
• Systemd: watchdog für automatischen Restart

8. Hugo-Integration

8.1 Shortcode-Integration

Kontaktformular:

{{< furt-contact
    form-id="contact-main"
    api-key="hugo-frontend-key"
    success-message="Vielen Dank für deine Nachricht!"
>}}

Kommentarsystem:

{{< furt-comments
    page-url="{{ .Permalink }}"
    api-key="sagjan-public-key"
    moderation="true"
>}}

8.2 JavaScript-Client

Minimaler, Framework-freier JavaScript-Client:

// pkg/client/furt-client.js
class FurtClient {
    constructor(baseURL, apiKey) {
        this.baseURL = baseURL;
        this.apiKey = apiKey;
    }
    
    async submitForm(formData, endpoint) {
        // Progressive Enhancement
        // Funktioniert mit und ohne JavaScript
    }
}

9. Git-Workflow und Versionierung

9.1 Branch-Strategie

• main: Stabile Releases
• develop: Hauptentwicklungszweig
• feature/*: Feature-Branches
• service/*: Service-spezifische Entwicklung
• release/*: Release-Kandidaten

9.2 Commit-Message-Format

typ(bereich): short description of the change

Detailed explanation of the change, if necessary.
Multiple lines possible.

Resolves: #123

• Typen: feat, fix, docs, style, refactor, test, chore
• Bereiche: gateway, service-*, config, docs, scripts
• Sprache: Englisch für alle Commit-Messages

9.3 Versionierung

Semantic Versioning (MAJOR.MINOR.PATCH):

• MAJOR: Breaking Changes in Gateway-API oder Service-Interfaces
• MINOR: Neue Services oder Features (abwärtskompatibel)
• PATCH: Bugfixes und Performance-Verbesserungen

10. Service-Spezifikationen

10.1 Formular2Mail-Service

Zweck: Kontaktformulare zu E-Mail weiterleiten Port: 8081 API: /send (POST) Integration: SMTP mit bestehendem Postfix Hugo-Integration: Shortcode für Kontaktformulare

10.2 Sagjan-Service (geplant)

Zweck: Kommentarsystem-Integration Port: 8082 API: /comments/* (GET, POST, PUT, DELETE) Features: Moderation, Threading, Spam-Schutz Hugo-Integration: Shortcode für Kommentare

10.3 Zukünftige Services

• Shop-Service: E-Commerce-Funktionen
• Newsletter-Service: Listmonk-Integration
• Calendar-Service: Terminbuchungen
• Auth-Service: User-Management

11. Lizenzierung

11.1 Apache License 2.0

Das Projekt steht unter der Apache License 2.0, die:

• Kommerzielle Nutzung erlaubt
• Patentrechte explizit gewährt
• Modifikationen ermöglicht
• Verteilung gestattet

11.2 Copyright-Header

Jede Quellcode-Datei muss folgenden Header enthalten:

// Copyright 2025 Furt Contributors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

12. Nächste Schritte

12.1 Unmittelbare Implementierung (Wurzelphase)

1. Gateway-Grundgerüst entwickeln

   • HTTP-Server mit grundlegenden Routen
   • Konfigurationsmanagement (YAML-basiert)
   • Service-Registry-Implementation

2. Formular2Mail-Service implementieren

   • SMTP-Integration mit bestehendem Postfix
   • Input-Validierung und Fehlerbehandlung
   • Hugo-Shortcode für Kontaktformulare

3. Apache-Integration konfigurieren

   • Reverse-Proxy für api.dragons-at-work.de
   • SSL-Terminierung und Header-Forwarding
   • Health-Check-Integration

12.2 Mittelfristige Entwicklung (Wachstumsphase)

1. Authentifizierungs-System ausbauen

   • Granulare API-Key-Berechtigungen
   • Rate-Limiting und IP-Restrictions
   • Admin-Interface für Key-Management

2. Monitoring und Logging

   • Strukturiertes JSON-Logging
   • Health-Check-Aggregation
   • Performance-Metriken

3. Service-Generator implementieren

   • Scaffolding für neue Services
   • Template-basierte Code-Generierung
   • Deployment-Script-Integration

---

Diese Konzeptdokumentation dient als Leitfaden für die Entwicklung von Furt und soll im Laufe des Projekts entsprechend der Erkenntnisse aus der praktischen Umsetzung angepasst und erweitert werden. Sie bildet die Grundlage für alle weiteren Architektur- und Implementierungsentscheidungen im Projekt.