Zum Hauptinhalt springen

Entwicklerdokumentation

Willkommen zur technischen Dokumentation der Hoffnungsträger Sprachbrücke. Diese Sektion richtet sich an Entwickler, die an der Plattform arbeiten oder Integrationen entwickeln.

🏗️ Architektur Überblick​

Die Sprachbrücke besteht aus mehreren miteinander verbundenen Komponenten:

Technologie-Stack​

KomponenteTechnologieZweck
BackendLaravel 12 + PHP 8.2+REST API, Business Logic
FrontendNext.js 15 + React 19Client Web Application
DatabasePostgreSQL 16Hauptdatenbank
AdminLaravel Filament v3.3Admin Dashboard
MobileIonic 8 + Capacitor 7Sprachmittler Mobile App
DocsDocusaurus 3Dokumentation

🚀 Schnellstart​

Voraussetzungen​

  • Node.js 22+ mit PNPM
  • PHP 8.3+ mit Composer
  • PostgreSQL 16+
  • Git

Installation​

# Repository klonen
git clone https://github.com/hoffnungstraeger-foundation/sprachbruecke.git
cd sprachbruecke

# Dependencies installieren (Monorepo)
pnpm install

# Umgebungsvariablen einrichten
cp .env.example .env
# .env Datei mit Datenbankverbindung konfigurieren

# Datenbank migrations ausführen
cd apps/backend
php artisan migrate

# Development server starten
pnpm dev

Detaillierte Anweisungen finden Sie unter Installation wird in Kürze dokumentiert.

🛠️ Entwicklungstools​

MCP (Model Context Protocol) Tools​

Die Entwicklung nutzt spezialisierte MCP-Tools für optimale Produktivität:

  • Context7 MCP - Framework-Dokumentation und Best Practices
  • PostgreSQL MCP - Datenbankoperationen und Überwachung
  • Task Master MCP - KI-gestützte Projektorganisation

Mehr Details: MCP Tools Dokumentation wird in Kürze verfügbar sein

Konventionen​

  • Git Commits: Conventional Commits Format (type(scope): description)
  • Code Style: ESLint + Prettier für Frontend, PSR-12 für Backend
  • Dokumentation: German-first Approach mit English Fallback
  • Testing: Jest + PHPUnit mit hoher Code Coverage

📁 Projektstruktur​

sprachbruecke/
├── apps/
│   ├── web/                 # Next.js Frontend
│   ├── backend/             # Laravel API  
│   ├── mobile/              # Mobile App
│   ├── admin/               # Filament Admin
│   └── docs/                # Docusaurus Docs
├── packages/                # Shared Libraries
├── knowledge/               # Development Knowledge Base
├── tasks/                   # Task Master Files
└── scripts/                 # Build & Deployment Scripts

🔄 Entwicklungsworkflow​

1. MCP Tools Workflow​

1. Context7: Framework-Dokumentation recherchieren
2. PostgreSQL MCP: Datenbankstatus prüfen  
3. Task Master: Nächste Aufgabe identifizieren
4. Implementation: Code entwickeln
5. Documentation: Änderungen dokumentieren
6. Git CLI: Conventional Commit erstellen

2. Feature Entwicklung​

  1. Task prüfen - Task Master für aktuelle Aufgaben verwenden
  2. Research - Context7 für Framework Best Practices
  3. Datenbank - PostgreSQL MCP für Schema-Änderungen
  4. Implementation - Code nach etablierten Patterns
  5. Tests - Unit & Integration Tests schreiben
  6. Dokumentation - Docusaurus aktualisieren
  7. Review - Pull Request mit Documentation

3. API Entwicklung​

  • Laravel Routes mit Resource Controllers
  • Form Requests für Validierung
  • API Resources für Response Transformation
  • OpenAPI Dokumentation automatisch generiert
  • Postman Collections für Testing

🧪 Testing Strategy​

Backend Testing (Laravel)​

// Unit Tests
php artisan test --testsuite=Unit

// Feature Tests (API Integration)
php artisan test --testsuite=Feature

// Code Coverage
php artisan test --coverage

Frontend Testing (Next.js)​

# Unit Tests (Jest + React Testing Library)
pnpm test

# E2E Tests (Playwright)
pnpm test:e2e

# Coverage Report
pnpm test:coverage

Database Testing​

  • PostgreSQL MCP für Performance-Analyse
  • Migration Testing auf Test-Datenbank
  • Query Optimization mit EXPLAIN-Plänen

🔐 Sicherheit & Compliance​

DSGVO (GDPR) Compliance​

  • Data Minimization - Nur notwendige Daten speichern
  • Right to be Forgotten - Löschfunktionalität implementiert
  • Data Portability - Export-Funktionen verfügbar
  • Audit Logging - Vollständige Nachverfolgung

Security Best Practices​

  • Authentication - JWT + Session-basiert
  • Authorization - Role-based Access Control (RBAC)
  • Input Validation - Server-side Validierung
  • SQL Injection Prevention - ORM + Prepared Statements
  • XSS Protection - Content Security Policy (CSP)

📚 Weitere Ressourcen​

Architektur​

  • System Überblick wird in Kürze dokumentiert - Gesamtarchitektur
  • Datenbank Design wird in Kürze dokumentiert - PostgreSQL Schema
  • API Design wird in Kürze dokumentiert - REST API Principles

Spezifische Guides​

  • Backend Setup wird in Kürze dokumentiert - Laravel Konfiguration
  • Frontend Setup wird in Kürze dokumentiert - Next.js Konfiguration
  • Mobile Development wird in Kürze dokumentiert - Mobile App Entwicklung

Integration​

  • API Referenz - Vollständige API Dokumentation
  • Webhooks werden in Kürze dokumentiert - Event-basierte Integration
  • Admin Interface wird in Kürze dokumentiert - Filament Dashboard
Entwicklungsregeln

Befolgen Sie die etablierten Cursor Rules für konsistente Code-Qualität und optimale Tool-Integration.

Nächste Schritte: Beginnen Sie mit der Installation oder erkunden Sie die Architektur.