docs(report): add section 5.3 draft assets

docs/temp-section-5-3-diagrams/5.3.1-server-bootstrap.md

@@ -0,0 +1,29 @@
+# 5.3.1 Server Bootstrap and Runtime Setup
+
+This diagram shows how the backend starts, mounts services, and becomes ready to handle API and realtime traffic.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Node as Node Runtime
+    participant Index as Backend/index.ts
+    participant App as Express App
+    participant Auth as Better Auth
+    participant Routes as Route Modules
+    participant MinIO as MinIO
+    participant RT as Socket.IO Gateway
+    participant Rec as Recordings Worker
+    participant Push as Push Worker
+
+    Node->>Index: start process
+    Index->>App: create express app
+    Index->>App: configure helmet + cors + JSON middleware
+    Index->>Auth: mount /api/auth/*
+    Index->>Routes: mount videos/admin/devices/links/streams/events/recordings/ops
+    Index->>MinIO: ensureMinioBucket()
+    MinIO-->>Index: bucket ready
+    Index->>RT: setupRealtimeGateway(server)
+    Index->>Rec: startRecordingsWorker()
+    Index->>Push: startPushWorker()
+    Index->>App: listen on configured port
+```

docs/temp-section-5-3-diagrams/5.3.10-operational-and-support-assets.md

@@ -0,0 +1,29 @@
+# 5.3.10 Operational Documentation and Support Assets
+
+This diagram maps the implementation code to the support assets used to inspect, document, and validate the system.
+
+```mermaid
+flowchart TD
+    Runtime[Runtime System]
+    APIs[API Routes]
+    Docs[OpenAPI Docs]
+    Sim[Simulator Pages]
+    Workers[Background Workers]
+    Validation[Validation and rollout docs]
+    Admin[Admin / Ops routes]
+
+    Runtime --> APIs
+    Runtime --> Workers
+    Runtime --> Admin
+    APIs --> Docs
+    APIs --> Sim
+    Runtime --> Validation
+
+    subgraph Support["Support layer"]
+        Docs
+        Sim
+        Workers
+        Validation
+        Admin
+    end
+```

docs/temp-section-5-3-diagrams/5.3.2-authentication-and-sessions.md

@@ -0,0 +1,30 @@
+# 5.3.2 User Authentication and Session Handling
+
+This diagram separates human user authentication from device-level authentication.
+
+```mermaid
+flowchart LR
+    User[User in Browser]
+    AuthAPI[/Better Auth Endpoints/]
+    Session[(session table)]
+    Users[(users table)]
+    Accounts[(account table)]
+    DeviceReg[/Device Registration API/]
+    DeviceToken[Signed Device Token]
+    DeviceAPI[/Device Auth Routes/]
+
+    User -->|sign up / sign in| AuthAPI
+    AuthAPI --> Users
+    AuthAPI --> Accounts
+    AuthAPI --> Session
+    Session -->|cookie-backed session| User
+
+    User -->|authenticated session| DeviceReg
+    DeviceReg -->|register browser as camera/client| DeviceToken
+    DeviceToken --> DeviceAPI
+
+    classDef auth fill:#e8f1ff,stroke:#2563eb,stroke-width:2px,color:#111827;
+    classDef data fill:#fff7e8,stroke:#d97706,stroke-width:2px,color:#111827;
+    class AuthAPI,DeviceReg,DeviceAPI,DeviceToken auth;
+    class Session,Users,Accounts data;
+```

docs/temp-section-5-3-diagrams/5.3.3-device-registration-and-presence.md

@@ -0,0 +1,26 @@
+# 5.3.3 Device Identity Registration and Presence
+
+This diagram shows how a signed-in user registers a browser as a device and how presence is maintained after realtime connection.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant User as Signed-in User
+    participant Web as WebApp Controller
+    participant Devices as POST /devices/register
+    participant DB as devices + device_links
+    participant Token as Device Token
+    participant Socket as Socket.IO Gateway
+
+    User->>Web: submit onboarding role + name
+    Web->>Devices: register device
+    Devices->>DB: insert devices row
+    Devices->>DB: auto-link to opposite-role devices if present
+    Devices-->>Web: return device + deviceToken
+    Web->>Web: persist saved device record
+    Web->>Socket: connect with device token
+    Socket->>DB: mark device online
+    Web->>Socket: periodic heartbeat
+    Socket->>DB: update lastSeenAt and status
+    Socket-->>Web: connection + heartbeat acknowledgements
+```

docs/temp-section-5-3-diagrams/5.3.4-database-schema-and-persistence.md

@@ -0,0 +1,97 @@
+# 5.3.4 Database Schema and Persistence Model
+
+## Core Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    USERS ||--o{ DEVICES : owns
+    USERS ||--o{ DEVICE_LINKS : owns
+    DEVICES ||--o{ DEVICE_LINKS : cameraDeviceId
+    DEVICES ||--o{ DEVICE_LINKS : clientDeviceId
+    USERS ||--o{ STREAM_SESSIONS : owns
+    DEVICES ||--o{ STREAM_SESSIONS : cameraDeviceId
+    DEVICES ||--o{ STREAM_SESSIONS : requesterDeviceId
+
+    USERS {
+      uuid id PK
+      varchar email
+      varchar name
+    }
+    DEVICES {
+      uuid id PK
+      uuid user_id FK
+      varchar role
+      varchar status
+      timestamp last_seen_at
+    }
+    DEVICE_LINKS {
+      uuid id PK
+      uuid owner_user_id FK
+      uuid camera_device_id FK
+      uuid client_device_id FK
+      varchar status
+    }
+    STREAM_SESSIONS {
+      uuid id PK
+      uuid owner_user_id FK
+      uuid camera_device_id FK
+      uuid requester_device_id FK
+      varchar status
+      varchar reason
+    }
+```
+
+## Media and Event Persistence
+
+```mermaid
+erDiagram
+    USERS ||--o{ EVENTS : owns
+    DEVICES ||--o{ EVENTS : triggeredBy
+    STREAM_SESSIONS ||--o{ RECORDINGS : produces
+    EVENTS ||--o{ RECORDINGS : mayCreate
+    USERS ||--o{ NOTIFICATIONS : receives
+    EVENTS ||--o{ NOTIFICATIONS : generates
+    USERS ||--o{ NOTIFICATION_DELIVERIES : owns
+    DEVICES ||--o{ NOTIFICATION_DELIVERIES : targets
+    USERS ||--o{ AUDIT_LOGS : owns
+    DEVICES ||--o{ AUDIT_LOGS : actor
+
+    EVENTS {
+      uuid id PK
+      uuid user_id FK
+      uuid device_id FK
+      varchar status
+      timestamp started_at
+      timestamp ended_at
+    }
+    RECORDINGS {
+      uuid id PK
+      uuid stream_session_id FK
+      uuid event_id FK
+      varchar object_key
+      varchar bucket
+      varchar status
+    }
+    NOTIFICATIONS {
+      uuid id PK
+      uuid event_id FK
+      uuid user_id FK
+      varchar channel
+      varchar status
+    }
+    NOTIFICATION_DELIVERIES {
+      uuid id PK
+      uuid recipient_device_id FK
+      varchar type
+      varchar status
+      int attempts
+    }
+    AUDIT_LOGS {
+      uuid id PK
+      uuid owner_user_id FK
+      uuid actor_device_id FK
+      varchar action
+      varchar target_type
+      varchar target_id
+    }
+```

docs/temp-section-5-3-diagrams/5.3.5-linking-and-control-flow.md

@@ -0,0 +1,36 @@
+# 5.3.5 Device Linking and Command-Oriented Control
+
+This comparison diagram contrasts the older command-driven path with the current simplified stream request path.
+
+```mermaid
+flowchart LR
+    subgraph Legacy["Legacy command-oriented path"]
+        LClient[Client Device]
+        LBackend[Backend]
+        LCmd[(commands table)]
+        LGateway[Realtime Gateway]
+        LCamera[Camera Device]
+
+        LClient -->|request stream| LBackend
+        LBackend --> LCmd
+        LCmd --> LGateway
+        LGateway -->|command:received| LCamera
+        LCamera -->|command:ack| LGateway
+        LGateway --> LBackend
+    end
+
+    subgraph Simple["Simplified linked-device path"]
+        SClient[Client Device]
+        SBackend[Backend]
+        SLinks[(device_links)]
+        SSession[(stream_sessions)]
+        SCamera[Camera Device]
+
+        SClient -->|request stream| SBackend
+        SBackend --> SLinks
+        SBackend --> SSession
+        SBackend -->|stream:requested| SCamera
+        SCamera -->|accept| SBackend
+        SBackend -->|stream:started| SClient
+    end
+```

docs/temp-section-5-3-diagrams/5.3.6-stream-sessions-and-signalling.md

@@ -0,0 +1,46 @@
+# 5.3.6 Stream Sessions and Signalling
+
+## Stream Request and WebRTC Signalling Sequence
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Client as Client Browser
+    participant Backend as Backend /streams
+    participant Links as device_links
+    participant Session as stream_sessions
+    participant Camera as Camera Browser
+    participant RT as Socket.IO Relay
+
+    Client->>Backend: POST /streams/request
+    Backend->>Links: verify active camera-client link
+    Backend->>Session: insert requested session
+    Backend->>Camera: emit stream:requested
+    Camera->>Backend: POST /streams/:id/accept
+    Backend->>Session: update status to streaming
+    Backend->>Client: emit stream:started
+    Camera->>RT: webrtc:signal offer
+    RT->>Client: relay offer
+    Client->>RT: webrtc:signal answer
+    RT->>Camera: relay answer
+    Client->>RT: ICE candidates
+    RT->>Camera: relay ICE candidates
+    Camera->>RT: ICE candidates
+    RT->>Client: relay ICE candidates
+```
+
+## Stream Session State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> requested
+    requested --> streaming: camera accepts
+    requested --> cancelled: requester cancels
+    requested --> failed: validation or delivery failure
+    streaming --> completed: normal end
+    streaming --> cancelled: manual stop
+    streaming --> failed: connection or upload failure
+    completed --> [*]
+    cancelled --> [*]
+    failed --> [*]
+```

docs/temp-section-5-3-diagrams/5.3.7-motion-events-notifications-audit.md

@@ -0,0 +1,42 @@
+# 5.3.7 Motion Events Notifications and Audit Trail
+
+## Motion Event Lifecycle
+
+```mermaid
+flowchart TD
+    Trigger[Manual trigger or browser motion detector]
+    Start[/POST /events/motion/start/]
+    Event[(events table)]
+    Links[(device_links)]
+    RT[Realtime motion:detected]
+    Push[Queued push notification]
+    End[/POST /events/:id/motion/end/]
+
+    Trigger --> Start
+    Start --> Event
+    Start --> Links
+    Links --> RT
+    Links --> Push
+    RT --> End
+    Push --> End
+    End --> Event
+```
+
+## Activity and Audit Flow
+
+```mermaid
+flowchart LR
+    Camera[Camera Device]
+    Event[(events)]
+    Notif[(notifications)]
+    Delivery[(notification_deliveries)]
+    Audit[(audit_logs)]
+    Client[Client Device]
+
+    Camera --> Event
+    Event --> Notif
+    Event --> Delivery
+    Event --> Audit
+    Notif --> Client
+    Delivery --> Client
+```

docs/temp-section-5-3-diagrams/5.3.8-recordings-and-object-storage.md

@@ -0,0 +1,40 @@
+# 5.3.8 Recordings and Object Storage
+
+## Recording Pipeline
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Cam as Camera Browser
+    participant Ctrl as Web Controller
+    participant Videos as /videos/upload-url
+    participant MinIO as MinIO Object Storage
+    participant Rec as /recordings/:id/finalize
+    participant DB as recordings table
+    participant Viewer as Client Browser
+
+    Cam->>Ctrl: stop local MediaRecorder
+    Ctrl->>Ctrl: compress recording blob
+    Ctrl->>Videos: request presigned upload URL
+    Videos-->>Ctrl: objectKey + uploadUrl
+    Ctrl->>MinIO: PUT recording blob
+    Ctrl->>Rec: finalize recording metadata
+    Rec->>DB: mark recording ready
+    Viewer->>Rec: GET /recordings/:id/download-url
+    Rec-->>Viewer: presigned download URL
+```
+
+## Storage Architecture
+
+```mermaid
+flowchart LR
+    Backend[Backend Service]
+    PG[(Postgres)]
+    MinIO[(MinIO / S3)]
+    Web[Web Client]
+
+    Web -->|stream, event, recording metadata| Backend
+    Backend -->|users, devices, links, sessions, events, recordings| PG
+    Backend -->|presigned upload/download + object checks| MinIO
+    Web -->|PUT / GET via presigned URLs| MinIO
+```

docs/temp-section-5-3-diagrams/5.3.9-web-application-implementation.md

@@ -0,0 +1,53 @@
+# 5.3.9 Web Application Implementation
+
+## Web Application Architecture
+
+```mermaid
+flowchart LR
+    Routes[Svelte Route Pages]
+    Controller[controller.js]
+    Store[store.js]
+    API[api.js]
+    Socket[Socket.IO Client]
+    Backend[Backend APIs]
+
+    Routes --> Controller
+    Controller --> Store
+    Controller --> API
+    Controller --> Socket
+    API --> Backend
+    Socket --> Backend
+
+    subgraph RoutePages["Main route pages"]
+        Auth[Auth]
+        Onboarding[Onboarding]
+        Camera[Camera]
+        Client[Client]
+        Activity[Activity]
+        Settings[Settings]
+    end
+
+    Routes --> RoutePages
+```
+
+## UI Flow
+
+```mermaid
+flowchart TD
+    Start[Open WebApp]
+    Auth[Sign in / Sign up]
+    Onboarding[Register browser as device]
+    Role{Chosen role}
+    Camera[Camera dashboard]
+    Client[Client dashboard]
+    Activity[Activity page]
+    Settings[Settings page]
+
+    Start --> Auth --> Onboarding --> Role
+    Role -->|camera| Camera
+    Role -->|client| Client
+    Camera --> Activity
+    Camera --> Settings
+    Client --> Activity
+    Client --> Settings
+```

docs/temp-section-5-3-diagrams/README.md

@@ -0,0 +1,18 @@
+# Temporary Section 5.3 Diagrams
+
+These temporary files contain Mermaid diagrams for the `5.3` implementation chapter.
+
+## Files
+
+- [5.3.1 Server Bootstrap](./5.3.1-server-bootstrap.md)
+- [5.3.2 Authentication and Sessions](./5.3.2-authentication-and-sessions.md)
+- [5.3.3 Device Registration and Presence](./5.3.3-device-registration-and-presence.md)
+- [5.3.4 Database Schema and Persistence](./5.3.4-database-schema-and-persistence.md)
+- [5.3.5 Linking and Control Flow](./5.3.5-linking-and-control-flow.md)
+- [5.3.6 Stream Sessions and Signalling](./5.3.6-stream-sessions-and-signalling.md)
+- [5.3.7 Motion Events Notifications Audit](./5.3.7-motion-events-notifications-audit.md)
+- [5.3.8 Recordings and Object Storage](./5.3.8-recordings-and-object-storage.md)
+- [5.3.9 Web Application Implementation](./5.3.9-web-application-implementation.md)
+- [5.3.10 Operational and Support Assets](./5.3.10-operational-and-support-assets.md)
+
+These are temporary working diagrams intended for screenshots and report drafting.