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

Komponente	Technologie	Zweck
Backend	Laravel 12 + PHP 8.2+	REST API, Business Logic
Frontend	Next.js 15 + React 19	Client Web Application
Database	PostgreSQL 16	Hauptdatenbank
Admin	Laravel Filament v3.3	Admin Dashboard
Mobile	Ionic 8 + Capacitor 7	Sprachmittler Mobile App
Docs	Docusaurus 3	Dokumentation

Projektstruktur

sprachbruecke/
├── apps/
│   ├── api/                  # Laravel API + Filament Admin
│   ├── web/                  # Next.js Frontend
│   ├── mobile-ionic/         # Ionic Mobile App
│   └── docs/                 # Docusaurus Dokumentation
├── packages/                 # Shared Libraries (falls vorhanden)
├── knowledge/                # Projekt-Dokumentation
└── thoughts/                 # Claude Code Notizen

Schnellstart

Voraussetzungen

• Node.js 22+ mit Yarn
• PHP 8.2+ mit Composer
• PostgreSQL 16+
• Git

Installation

# Repository klonen
git clone <repository-url>
cd hoffnungstraeger-sprachbruecke

# Dependencies installieren (Monorepo)
yarn install

# API Setup
cd apps/api
cp .env.example .env
# .env mit Datenbankverbindung konfigurieren
php artisan key:generate
php artisan migrate
php artisan db:seed

# Zurück zum Root
cd ../..

# Development Server starten
yarn dev

Entwicklungsserver

App	Port	Befehl
API (Laravel)	8000	yarn dev:api
Web (Next.js)	3004	yarn dev:web
Mobile (Ionic)	8100	yarn dev:mobile
Docs (Docusaurus)	3005	yarn dev:docs

Dokumentations-Übersicht

Backend

• Kerngeschäftslogik - Services, Actions, Business Logic
• State Management - Spatie Model States für Orders/Users
• Kostenberechnung - Tarif-System und Rechnungsstellung
• Case Conversion Middleware - camelCase/snake_case Transformation

Frontend

• Mobile App (Ionic) - Architektur für Sprachmittler-App
• Web App (Next.js) - Architektur für Auftraggeber-Portal
• API Client - Shared API Client Implementierung
• Dashboard System - Widget-System

Workflows

• Allgemeine Workflows - System-Workflows
• Order Request Workflow - Sprachmittler-Matching

Weitere

• Datenbank-Schema - ER-Diagramm
• Performance - Optimierungen

Konventionen

Git Commits

Conventional Commits Format:

type(scope): description

feat(orders): add cancellation workflow
fix(api): handle missing interpreter gracefully
docs(admin): update resource documentation

Code Style

Sprache	Standard	Tool
PHP	PSR-12	Laravel Pint
TypeScript	Prettier + ESLint	-
SQL	-	-

Dokumentation

• Sprache: Deutsch (primär), Englisch (API-Referenz)
• Format: Markdown mit Mermaid-Diagrammen
• Speicherort: apps/docs/docs/

Testing

Backend (Laravel)

cd apps/api

# Alle Tests
composer test

# Einzelner Test
php artisan test --filter=OrderControllerTest

# Mit Coverage
php artisan test --coverage

Frontend

# Web
cd apps/web
npm run test

# Mobile
cd apps/mobile-ionic
npm run test

Sicherheit & Compliance

DSGVO Compliance

• Datensparsamkeit: Nur notwendige Daten
• Recht auf Löschung: Implementiert via User-Deaktivierung
• Datenportabilität: Export-Funktionen
• Audit-Logging: Spatie Activity Log

Security Best Practices

• Authentication: Laravel Sanctum (Token-basiert)
• Authorization: Spatie Laravel Permission (RBAC)
• Input Validation: Form Requests
• SQL Injection: Eloquent ORM
• XSS Protection: Blade Escaping, CSP Headers

Weiterführende Links

• System-Übersicht - Gesamtarchitektur
• API-Referenz - OpenAPI Dokumentation
• Admin-Panel (Entwickler) - Filament Dokumentation
• Benachrichtigungen - Notification System

---

Entwicklungsregeln

Alle Entwickler sollten die CLAUDE.md im Repository-Root lesen, die projekt-spezifische Anweisungen enthält.