Architecture & API Reference

Developer Documentation & Architecture

This documentation provides an in-depth reference for software engineers and integrators working with the Bobine platform: architecture, local REST API endpoints, real-time WebSocket protocol, background systemd supervisors, and AGPL-3.0 contribution guidelines.

100% Local & Privacy-Preserving

All APIs and WebSocket streams run exclusively on the local network (LAN / Wi-Fi) of the mini PC. No media, authentication keys, or analytics are ever transmitted to third-party cloud servers.

Software Stack

Layer	Technology	Role & Responsibility
Backend API	Python 3.11+, FastAPI, Uvicorn	High-throughput asynchronous REST API and WebSocket events
Persistence	SQLite + SQLAlchemy 2.0	Workout metadata, weekly schedules, playlists, and settings
Playout Engine	MPV + VA-API (Intel iHD & AMD mesa-va-drivers)	Zero-copy hardware video decoding (1080p60 & 4K) via IPC Unix socket
Frontend UI	Next.js 16 (App Router), React 19, TS	Universal responsive web app (Admin, Kiosk, Remote, Radio)
Audio Routing	ALSA	Multi-channel audio output routing and volume control

Local Development Workflow & Interactive API Console

Prerequisites: Node.js ≥ 20, Python ≥ 3.11.

Start Backend API Server with Hot Reloading

Launches FastAPI on port 8000 with interactive Swagger docs accessible at http://localhost:8000/docs.

bash — bobine dev environment & api console

fanta@wyse:~$cd backend && .venv/bin/uvicorn app.main:app --reload --port 8000

INFO: Will watch for changes in ['/home/fanta/Bobine/backend']

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

INFO: Started reloader process [19450] using WatchFiles

INFO: FastAPI app initialized: routes registered (/api/playback, /api/settings, /api/audio, /api/kiosk)

Interactive OpenAPI documentation available at http://127.0.0.1:8000/docs

Local REST API Reference

The Bobine daemon exposes a clean, typed REST API on http://bobine.local/api (or http://127.0.0.1:8000/api):

GET/api/health

Machine-readable health check endpoint queried continuously by the systemd watchdog.

// Response (200 OK)
{
  "status": "healthy",
  "database": "ok",
  "kiosk_active": true,
  "uptime_seconds": 86420
}

GET/api/status

Returns the real-time playback state, active workout, progress, and screen routing status.

// Response (200 OK)
{
  "state": "playing",
  "current_workout": {
    "id": "w_982a7f",
    "title": "RPM Sprint 45",
    "category": "Spinning",
    "duration_seconds": 2700
  },
  "timecode": 1420.5,
  "volume": 80,
  "next_scheduled_class": {
    "title": "Yoga Vinyasa",
    "starts_in_seconds": 840
  }
}

POST/api/playout/play

Starts immediate video playout for a specified workout ID.

// Request body
{ "workout_id": "w_982a7f", "target_display": "hdmi_wired" }

// Response (200 OK)
{ "success": true, "message": "Playout started" }

POST/api/playout/volume

Adjusts master hardware sound volume level (0 to 100).

// Request body
{ "level": 85 }

// Response (200 OK)
{ "success": true, "current_volume": 85 }

POST/api/backup/export

Generates a full ZIP export of the video library, schedule, and settings for backup or migration.

Real-Time WebSocket Protocol

WS/ws/events

Clients connect to ws://bobine.local/ws/events to receive instantaneous state changes across all devices:

// Broadcast event on state change:
{
  "event": "PLAYBACK_STATE_CHANGED",
  "payload": {
    "state": "playing",
    "workout_id": "w_982a7f",
    "timecode": 45.2,
    "volume": 80
  }
}

Systemd Supervisor Architecture

Bobine is managed by 3 isolated systemd services for fault tolerance:

bobine-backend.service — Python FastAPI application and SQLite daemon.
bobine-kiosk.service — Lightweight X11 session running Chromium in kiosk mode displaying the wired cinema screen.
bobine-watchdog.service — Proactive health supervisor polling /api/health every 10s and triggering automated component restarts if needed.

Community, Contact & Contribution

Bobine is licensed under the AGPL-3.0 copyleft license. We welcome contributions, bug reports, and hardware compatibility tests.