Diese Anleitung behandelt den täglichen Entwicklungs-Workflow für Beiträge zu Bedrud.

Repository-Struktur

bedrud/
├── server/          # Go backend
├── apps/
│   ├── web/         # React frontend (TanStack Start)
│   ├── android/     # Android app
│   ├── ios/         # iOS app
│   └── desktop/     # Desktop app (Rust + Slint)
├── agents/          # Python bot agents
├── packages/        # Shared TypeScript types
├── tools/cli/       # Deployment CLI
├── docs/            # Documentation (MkDocs)
├── Cargo.toml       # Rust workspace root
├── Makefile         # Build orchestration
└── Dockerfile       # Container build

Voraussetzungen

Ersteinrichtung

git clone https://github.com/bedrud-ir/bedrud.git
cd bedrud
make init

Full-Stack-Entwicklung

Um den gesamten Stack lokal auszuführen:

make dev

Dies startet LiveKit, den Go-Server und den React-Dev-Server gleichzeitig. Drücken Sie Ctrl+C, um alle Prozesse zu stoppen.

Dienste einzeln ausführen

make dev-web

make dev-server

make dev-livekit

Server-Entwicklung

Der Einstiegspunkt des Go-Servers ist server/cmd/server/main.go.

Einen API-Endpunkt hinzufügen

1. Handler definieren in server/internal/handlers/
2. Repository-Methoden hinzufügen in server/internal/repository/, falls neue DB-Abfragen benötigt werden
3. Route registrieren im Server-Setup (normalerweise in main.go oder einer Routen-Datei)
4. Middleware hinzufügen, falls der Endpunkt Authentifizierung oder Admin-Prüfungen benötigt

Datenbankänderungen

Fügen Sie GORM-Model-Structs hinzu oder ändern Sie diese in server/internal/models/. GORM migriert automatisch beim Start.

Swagger-Dokumentation

API-Dokumentationsannotationen verwenden das swaggo-Format. Nach Änderungen neu generieren:

cd server
swag init -g cmd/server/main.go

Siehe Server-Architektur für das vollständige Verzeichnislayout und das Layered-Design.

Web-Frontend-Entwicklung

Das Frontend befindet sich in apps/web/ und verwendet React 19 mit TanStack Start.

Eine Seite hinzufügen

Erstellen Sie eine neue Datei unter src/routes/ gemäß der dateibasierten Routing-Konvention von TanStack Router (z. B. src/routes/settings.tsx). Exportieren Sie eine Route, die mit createFileRoute erstellt wurde.

Eine API-Client-Funktion hinzufügen

1. Funktion in src/lib/api.ts mit authFetch hinzufügen
2. TypeScript-Typen inline oder in einer gemeinsamen Typdatei definieren
3. Funktion aus Ihrer Routen-Komponente verwenden, typischerweise über einen TanStack Query useQuery-Hook

Typprüfung

cd apps/web
bun run check    # runs Biome lint + TypeScript type check

Siehe Web-Frontend-Architektur für die vollständige Frontend-Struktur und Muster.

Android-Entwicklung

make dev-android    # Opens in Android Studio

Wichtige Muster

• Alle Bildschirme sind Composable-Funktionen
• Abhängigkeiten kommen vom InstanceManager über koinInject()
• Verwenden Sie collectAsState().value ?: return für nullable StateFlow-Werte
• Navigation wird in MainActivity.kt verwaltet

Build

make build-android-debug    # Debug APK
make build-android          # Release APK (needs keystore)
make release-android        # Build + install on device

Siehe Android-App-Architektur für detaillierte mobile App-Architektur.

iOS-Entwicklung

make dev-ios    # Opens in Xcode

Wichtige Muster

• Views sind SwiftUI-Structs
• Abhängigkeiten kommen vom InstanceManager über @EnvironmentObject
• Verwenden Sie Optional Binding für nullable Published Properties
• Navigation verwendet den nativen Navigation-Stack von SwiftUI

Projektgenerierung

Wenn Sie project.yml ändern, generieren Sie das Xcode-Projekt neu:

cd apps/ios
xcodegen generate

Build

make build-ios          # Release archive
make build-ios-sim      # Simulator build
make export-ios         # Export IPA

Siehe iOS-App-Architektur für detaillierte mobile App-Architektur.

Desktop-Entwicklung

Die Desktop-App befindet sich in apps/desktop/ und ist ein Rust-Crate im Workspace.

Voraussetzungen (Linux)

sudo apt-get install -y \
  libfontconfig1-dev libxkbcommon-dev libxkbcommon-x11-dev \
  libwayland-dev libgles2-mesa-dev libegl1-mesa-dev \
  libdbus-1-dev libsecret-1-dev \
  libasound2-dev

Windows erfordert Visual Studio Build Tools mit der C++-Workload (MSVC).

Ausführen

make dev-desktop    # cargo run -p bedrud-desktop

Build

make build-desktop           # optimised binary for the current platform

Wichtige Muster

• Die gesamte UI ist in .slint-Dateien unter apps/desktop/ui/ definiert; wird zur Build-Zeit von build.rs zu Rust kompiliert
• apps/desktop/src/ui/bridge.rs ist der einzige Ort, an dem Slint-Callbacks mit Rust-Logik verbunden werden - halten Sie Geschäftslogik aus den .slint-Dateien heraus
• Verwenden Sie Weak<AppWindow>, wenn Sie Hintergrundaufgaben starten, die die UI aktualisieren müssen

Siehe Desktop-App-Architektur für detaillierte Desktop-App-Architektur.

Bot-Agenten-Entwicklung

Agenten befinden sich in agents/ mit einem Verzeichnis pro Agent.

cd agents/music_agent
pip install -r requirements.txt
python agent.py "http://localhost:8090/m/test-room"

Alle Agenten benötigen einen laufenden Bedrud-Server zur Authentifizierung.

CI/CD

GitHub Actions wird bei jedem Push auf main und bei Pull Requests ausgeführt:

Release-Builds werden durch Versions-Tags (v*) ausgelöst.

Code-Stil

• Go: Standard gofmt-Formatierung
• TypeScript/React: Biome (konfiguriert in apps/web/biome.json)
• Kotlin: Android Studio-Standardformatierung
• Swift: Xcode-Standardformatierung

Testing

cd server
go test ./...

cd apps/web
bun run check

cd apps/android
./gradlew test

make build-ios-sim   # Builds and runs tests

Siehe auch

• Makefile-Referenz - alle Build- und Dev-Befehle
• Architekturübersicht - wie die Komponenten zusammenpassen