Esta guía cubre el flujo de desarrollo diario para contribuir a Bedrud.

Estructura del repositorio

bedrud/
├── server/          # Backend en Go
├── apps/
│   ├── web/         # Frontend React (TanStack Start)
│   ├── android/     # Aplicación Android
│   ├── ios/         # Aplicación iOS
│   └── desktop/     # Aplicación de escritorio (Rust + Slint)
├── agents/          # Agentes bot en Python
├── packages/        # Tipos TypeScript compartidos
├── tools/cli/       # CLI de despliegue
├── docs/            # Documentación (MkDocs)
├── Cargo.toml       # Raíz del workspace Rust
├── Makefile         # Orquestación de builds
└── Dockerfile       # Build del contenedor

Requisitos previos

Configuración inicial

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

Desarrollo full-stack

Para ejecutar toda la pila localmente:

make dev

Esto inicia LiveKit, el servidor Go y el servidor de desarrollo de React simultáneamente. Presiona Ctrl+C para detener todos los procesos.

Ejecutar servicios individualmente

make dev-web

make dev-server

make dev-livekit

Desarrollo del servidor

El punto de entrada del servidor Go es server/cmd/server/main.go.

Añadir un endpoint de API

1. Define el handler en server/internal/handlers/
2. Añade métodos de repositorio en server/internal/repository/ si se necesitan nuevas consultas a la base de datos
3. Registra la ruta en la configuración del servidor (generalmente en main.go o un archivo de rutas)
4. Añade middleware si el endpoint requiere autenticación o verificación de administrador

Cambios en la base de datos

Añade o modifica estructuras de modelo GORM en server/internal/models/. GORM migra automáticamente al iniciar.

Documentación Swagger

Las anotaciones de documentación de la API usan el formato swaggo. Después de cambios, regenera:

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

Consulta Arquitectura del servidor para ver la estructura completa de directorios y el diseño por capas.

Desarrollo del frontend web

El frontend está en apps/web/ y usa React 19 con TanStack Start.

Añadir una página

Crea un nuevo archivo en src/routes/ siguiendo la convención de enrutamiento basado en archivos de TanStack Router (por ejemplo, src/routes/settings.tsx). Exporta un Route creado con createFileRoute.

Añadir una función de cliente de API

1. Añade la función en src/lib/api.ts usando authFetch
2. Define los tipos TypeScript en línea o en un archivo de tipos compartidos
3. Usa la función desde tu componente de ruta, típicamente a través de un hook useQuery de TanStack Query

Verificación de tipos

cd apps/web
bun run check    # ejecuta lint de Biome + verificación de tipos TypeScript

Consulta Arquitectura del frontend web para ver la estructura completa y patrones del frontend.

Desarrollo de Android

make dev-android    # Abre en Android Studio

Patrones clave

• Todas las pantallas son funciones Composable
• Las dependencias provienen de InstanceManager mediante koinInject()
• Usa collectAsState().value ?: return para valores anulables de StateFlow
• La navegación se maneja en MainActivity.kt

Compilación

make build-android-debug    # APK de depuración
make build-android          # APK de producción (necesita keystore)
make release-android        # Compilar + instalar en el dispositivo

Consulta Arquitectura de la aplicación Android para ver la arquitectura detallada de la aplicación móvil.

Desarrollo de iOS

make dev-ios    # Abre en Xcode

Patrones clave

• Las vistas son structs de SwiftUI
• Las dependencias provienen de InstanceManager mediante @EnvironmentObject
• Usa optional binding para propiedades published anulables
• La navegación usa la pila de navegación nativa de SwiftUI

Generación del proyecto

Si modificas project.yml, regenera el proyecto de Xcode:

cd apps/ios
xcodegen generate

Compilación

make build-ios          # Archivo de producción
make build-ios-sim      # Build para simulador
make export-ios         # Exportar IPA

Consulta Arquitectura de la aplicación iOS para ver la arquitectura detallada de la aplicación móvil.

Desarrollo de escritorio

La aplicación de escritorio está en apps/desktop/ y es un crate de Rust en el workspace.

Requisitos previos (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 requiere Visual Studio Build Tools con el workload de C++ (MSVC).

Ejecución

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

Compilación

make build-desktop           # binario optimizado para la plataforma actual

Patrones clave

• Toda la UI se define en archivos .slint en apps/desktop/ui/; se compila a Rust en tiempo de build por build.rs
• apps/desktop/src/ui/bridge.rs es el único lugar donde los callbacks de Slint se conectan con la lógica de Rust - mantén la lógica de negocio fuera de los archivos .slint
• Usa Weak<AppWindow> al lanzar tareas en segundo plano que necesitan actualizar la UI

Consulta Arquitectura de la aplicación de escritorio para ver la arquitectura detallada de la aplicación de escritorio.

Desarrollo de agentes bot

Los agentes están en agents/ con un directorio por agente.

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

Todos los agentes necesitan un servidor Bedrud en ejecución para autenticarse.

CI/CD

GitHub Actions se ejecuta en cada push a main y en pull requests:

Los builds de producción se disparan por tags de versión (v*).

Estilo de código

• Go: Formato estándar gofmt
• TypeScript/React: Biome (configurado en apps/web/biome.json)
• Kotlin: Formato predeterminado de Android Studio
• Swift: Formato predeterminado de Xcode

Tests

cd server
go test ./...

cd apps/web
bun run check

cd apps/android
./gradlew test

make build-ios-sim   # Compila y ejecuta tests

Consulta también

• Referencia del Makefile - todos los comandos de build y desarrollo
• Resumen de arquitectura - cómo se integran los componentes