Backend Architecture

:::info Status Implemented — reflects the current layout of fastapi-backend/. :::

Layout

Path	Role
main.py	App entry, WebSocket handlers (broadcast_endpoint, transmitter uplink), FFmpeg subprocess management, lifespan context (starts azan_scheduler, MQTT connection)
api/v1/endpoints/	Route handlers, one file per domain — see API Reference for the generated list
core/db.py	All database queries via asyncpg — the largest file in the codebase
core/ws.py	WebSocket connection manager (dashboard push, not the broadcast audio socket)
core/mqtt.py	MQTT broker connection (EMQX, async via aiomqtt)
core/live_broadcast.py	Broadcast started/ended fan-out: MQTT, push notifications, audit
core/azan_scheduler.py	Offline-azan fallback tick loop
core/expo_push.py, core/apns_voip_push.py, core/fcm_push.py, core/news_push.py	Push notification delivery per provider
core/device_authz.py, core/device_claim.py, core/device_trigger.py, core/device_status.py, core/device_alerts.py, core/device_outbox.py	Device lifecycle, authorization, and command delivery — see Device Architecture
core/audit_writer.py, core/audit_models.py	broadcast_audit_logs delivery analytics
icecast_helper.py	FFmpeg spawning, Icecast stream key management, ROOMS, active_broadcasters
schemas/	Pydantic request/response models, one file per domain
public/	Built frontend assets (website, admin-panel, super-admin-panel), served static by FastAPI

Request/response flow (typical REST call)

Why one database module

core/db.py centralizes every query rather than splitting a query layer per endpoint file. This keeps SQL — and therefore the actual schema contract — in one place, at the cost of the file's size (~145KB). See Database for how schema ownership is split between Alembic migrations and the ensure_* functions that still live in this file.

Real-time broadcasting

Admin Panel (browser) --WebSocket--> main.py
  --> spawns FFmpeg subprocess
    --> HTTP push to Icecast
      --> HTTPS stream URL to listeners (mobile/web/devices)

Full detail: Data Flow and Azaan Broadcast.

Device control

api/v1/endpoints/{devices,mosque-devices,device-registry,triggers}.py
  --MQTT publish--> EMQX broker
    --> device subscribes, acts, publishes status/ack back

Full detail: MQTT Protocol.

Testing

Tests run under pytest (config in fastapi-backend/pytest.ini); dev dependencies are isolated in requirements-dev.txt and excluded from the production image. test/conftest.py provisions a disposable Postgres automatically. See Testing.