1) System Context
+
+
+
+
+
+
+
+
+ Core Role
Acts primarily as a control plane for auth, command routing, stream state, credential issuance, and recording metadata. It is not yet a full production media plane.
Transport Split
HTTP handles CRUD/state endpoints; Socket.IO handles realtime command delivery, acknowledgements, and WebRTC signaling relay.
Persistence Split
Postgres stores state + metadata. MinIO stores binary objects. Routes often coordinate both.
2) Startup Sequence
+Process start
+ -> load module graph (auth, db, minio, routes)
+ -> create Express app + OpenAPI doc
+ -> mount middleware and routes
+ -> create HTTP server
+ -> start() called
+ -> ensureMinioBucket()
+ - checks bucket existence
+ - creates bucket if missing
+ - exits process on failure
+ -> setupRealtimeGateway(server)
+ - Socket.IO auth middleware
+ - event handlers
+ - command retry interval init (if required tables exist)
+ -> startRecordingsWorker()
+ - interval scans stale awaiting_upload rows -> failed
+ -> startPushWorker()
+ - interval dispatches queued push rows
+ -> server.listen(PORT)
+
+ If MinIO initialization fails, process exits with code 1 by design (index.ts).
+3) HTTP Request Pipeline (Express)
+
+
+
+ 4) Authentication and Identity Model
+
+
+
+
+ A) Session auth (requireAuth)
+-
+
- Used by user-facing REST routes like /videos, /devices/register, /device-links. +
- Reads Better Auth session from request headers/cookies via auth.api.getSession(). +
- Attaches session object to req.auth. +
- Backed by Better Auth tables: users, account, session, verification. +
+
+ B) Device auth (requireDeviceAuth)
+-
+
- Used by device-to-backend routes and Socket.IO auth. +
- Bearer token format: base64url(payload).hmac. +
- Payload fields: userId, deviceId, role, exp. +
- Signed with HMAC-SHA256 using BETTER_AUTH_SECRET. +
- Token role is verified against device role in realtime handshake. +
This dual model separates user session identity from per-device identity and permissions.
+5) Realtime Gateway (Socket.IO)
+
+
+
+
+
+ Connection model
+-
+
- Devices authenticate with token in handshake.auth.token or Authorization header. +
- Each device joins room device:{deviceId}. +
- Presence updates devices.status + lastSeenAt. +
- Disconnect applies a 500ms delay to reduce status flapping on fast reconnect. +
+
+ Gateway responsibilities
+-
+
- command:received delivery to target room. +
- command:ack validation + DB update + source notification. +
- webrtc:signal relay with same-owner target validation. +
- stream:frame relay fallback (base64 image snapshots). +
- Retry worker for stale sent commands every 5s, max 3 retries. +
Command dispatch and ack sequence
+Client Device API /commands DB Socket.IO Gateway Camera Device
+ | | | | |
+1) POST /commands -------->| validate/link ---->| insert queued command | |
+ | | dispatchCommandById() | |
+ | |-----------------------------------------------> emit command:received --->|
+ | | | status sent/queued | |
+ |<--------------------| command payload | | |
+
+2) camera emits command:ack --------------------------------------------------------------->|
+ | | | | validate + update DB |
+ | | | command status + ack time | emit command:status -->| (to source room)
+
+ 6) Stream Lifecycle and Media Control
+
+
+
+ State machine (stream session)
+requested --> streaming --> completed|cancelled|failed
+ | | |
+ | | +-- create recording placeholder row on end
+ | +-- media session created (provider + endpoints)
+ +-- command start_stream queued/dispatched to camera
+
+ On-demand stream end-to-end sequence
+Client Device /streams/request Camera Device /streams/:id/accept Media Provider
+ | | | | |
+1) request stream -------------->| validate roles/link -> | | |
+ | | create stream_session | | |
+ | | create start_stream cmd | | |
+ | | dispatch via socket ----+-------------------------> | command:received |
+ |<--------------------------| stream:requested event | | |
+
+2) accept command (camera side)
+ | | | POST /accept -----------> | createSession() ------>|
+ | | | | status=streaming |
+ |<--------------------------| stream:started event ---+ | |
+
+3) credential issuance
+camera -> GET /publish-credentials -> mediaProvider.issuePublishCredentials()
+viewer -> GET /subscribe-credentials -> mediaProvider.issueSubscribeCredentials()
+
+4) stream end
+camera/requester -> POST /end -> mark ended + optional sfuService.endSession() + createRecordingForStream()
+ -> emit stream:ended to camera and requester (push fallback if offline)
+
+
+
+
+
+
+ Media provider abstraction
+-
+
- Current provider: mock (media/providers/mock.ts). +
- Creates deterministic mock media session IDs. +
- Issues signed publish/subscribe tokens with TTL. +
- Uses BETTER_AUTH_SECRET for HMAC signing. +
+
+ SFU mode status
+-
+
- MEDIA_MODE=single_server_sfu enables SFU endpoints. +
- Current implementation is a noop scaffold with in-memory session registry + synthetic transport IDs. +
- No full server-side RTP forwarding pipeline implemented yet. +
7) Data Model (Core Tables and Relationships)
+
+
+
+ Note: notifications table exists for event notification tracking; push delivery queue is modeled separately by push_notifications.
+8) Route Surface and Responsibilities
+| Area | +Auth | +Main tables/resources | +Side effects | +
|---|---|---|---|
| /api/auth/* | +Better Auth | +users, account, session, verification | +session cookie lifecycle | +
| /devices | +session + device token for heartbeat | +devices, device_links | +auto-link opposite-role devices on register; stale-status projection on list | +
| /device-links | +session | +device_links, devices | +enforces camera/client role pairing | +
| /commands | +session + device token ack fallback | +device_commands, devices, device_links | +dispatch to Socket.IO, ack/reject propagation | +
| /events | +device token (start/end), session (list) | +events, device_links, notifications | +realtime motion fanout, push fallback, audit log | +
| /streams | +device token | +stream_sessions, device_commands, recordings | +stream command dispatch, media credentials, stream realtime events, push fallback, optional SFU calls | +
| /recordings | +device token | +recordings | +storage object validation, presigned download URL, audit log | +
| /videos | +session | +videos, devices, MinIO | +presigned PUT/GET generation, object listing/deletion | +
| /push-notifications | +device token | +push_notifications | +manual worker dispatch trigger | +
| /audit | +device token | +audit_logs | +none (read only) | +
| /ops | +none | +DB, MinIO, in-memory metrics, SFU service | +readiness checks, metric export | +
| /admin | +HTTP Basic auth | +MinIO | +embedded admin UI + object operations | +
Detailed endpoint groups
+
+
+ Devices and Links
+-
+
- POST /devices/register: creates device, sets initial online status, auto-creates links with existing opposite-role devices, returns device token. +
- GET /devices: lists user devices with computed effective presence status using DEVICE_ONLINE_STALE_SECONDS. +
- PATCH /devices/:id: updates mutable metadata and role. +
- POST /devices/:id/heartbeat: token-authenticated presence update for exact device token/device match. +
- /device-links: ensures one active camera-client pair and ownership checks. +
+
+ Commands, Events, Streams
+-
+
- POST /commands: only client -> camera, only for active links. +
- POST /events/motion/start: camera-only; sends realtime to linked clients, queues push if offline. +
- POST /streams/request: creates stream session + start_stream command + realtime notification. +
- POST /streams/:id/accept: camera transitions stream to streaming; creates media session and optional SFU bootstrap. +
- GET /streams/:id/publish-credentials: camera-only credential issuance. +
- GET /streams/:id/subscribe-credentials: participant credential issuance. +
- POST /streams/:id/end: closes session, ends SFU (if enabled), creates recording placeholder, notifies both parties. +
+
+ Storage and Recordings
+-
+
- POST /videos/upload-url: session route to mint presigned PUT + metadata row. +
- POST /recordings/:id/finalize: camera marks recording ready once object exists, or creates simulator placeholder if object key starts with sim/. +
- GET /recordings/:id/download-url: requester/camera only, ready-only, verifies object exists before presigning. +
9) Workers and Reliability Mechanisms
+
+
+
+
+ Command retry loop
+Inside realtime gateway. Scans device_commands where status is sent and stale by >10s. Re-dispatches every 5s. Fails after 3 retries.
+
+
+ Push worker
+Interval (default 10s) dispatches queued notifications with nextAttemptAt <= now. Missing push token triggers retry backoff; max attempts configurable.
+
+
+ Recording worker
+Interval (default 30s) marks stale awaiting_upload recordings as failed after timeout window (default 30 min).
+Workers perform startup guards using hasRequiredTables() so they do not run before migrations are applied.
+10) Security Controls and Guardrails
+
+
+
+
+ Implemented
+-
+
- Helmet CSP with explicit script/style/font/connect/media/image directives. +
- CORS tied to BETTER_AUTH_TRUSTED_ORIGINS (or permissive fallback). +
- Rate limiting globally and on high-traffic route groups. +
- Ownership checks on almost all queries (user-scoped data access). +
- Role constraints (for example client->camera command direction). +
- Token integrity via timing-safe HMAC verification. +
+
+ Important caveats
+-
+
- Rate limits are in-memory; not shared across replicas. +
- Metrics are in-memory counters only (no persistence/export protocol). +
- Mock push provider treats presence of push token as delivery success. +
- Mock media provider + SFU scaffold are not production media infrastructure. +
11) Configuration Map (Key Env Variables)
+| Domain | +Variables | +Architectural effect | +
|---|---|---|
| Core server | +PORT, DATABASE_URL | +listener + DB connectivity | +
| Auth | +BETTER_AUTH_SECRET, BETTER_AUTH_BASE_URL, BETTER_AUTH_TRUSTED_ORIGINS | +session signing, base URL, trusted origins, device token signing | +
| Presence | +DEVICE_ONLINE_STALE_SECONDS | +effective online/offline projection in device listings | +
| Storage | +MINIO_ENDPOINT, MINIO_PORT, MINIO_USE_SSL, MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_BUCKET, MINIO_PRESIGNED_EXPIRY_SECONDS | +object I/O, presign TTL, startup bucket bootstrap | +
| Media | +MEDIA_MODE, MEDIA_PROVIDER, TURN_URLS, TURN_USERNAME, TURN_CREDENTIAL | +control plane mode and transport descriptor generation | +
| Workers | +PUSH_WORKER_INTERVAL_MS, PUSH_MAX_ATTEMPTS, RECORDING_WORKER_INTERVAL_MS, RECORDING_STALE_SECONDS | +queue throughput, retry/failure timing | +
| Admin | +ADMIN_USERNAME, ADMIN_PASSWORD | +required to mount admin dashboard route logic | +
12) Code Ownership Map (Where to Modify What)
+
+
+
+
+ Server composition
+index.ts: middleware stack, route mounting, startup ordering, workers, realtime setup.
+Identity
+auth.ts, middleware/auth.ts, middleware/device-auth.ts, utils/device-token.ts.
+Persistence schema
+db/schema.ts + drizzle/* migrations.
+
+
+ Realtime + command delivery
+realtime/gateway.ts and routes/commands.ts.
+Streaming control
+routes/streams.ts, media/*, routes/recordings.ts.
+Operational views
+routes/ops.ts, observability/metrics.ts, routes/admin.ts.
+13) Current Constraints and Scaling Boundaries
+
+
+
+
+ State locality
+Presence, rate-limit counters, metrics counters, and SFU registry are process-local. Horizontal scaling requires external shared state.
+
+
+ Media realism
+Media provider is mock; SFU service is scaffold/noop. Production deployment needs real media infrastructure for reliability and scale.
+
+
+ Queue semantics
+Push and command retries are interval-based polling workers. Throughput, ordering guarantees, and dead-letter handling are minimal.
+For load-bearing evolution, the natural next architecture step is extracting shared state (Redis/queue), production media plane, and distributed rate/metrics telemetry.
+