docs(project): add planning diagrams and report deliverables

docs/architecture-diagram.md

@@ -0,0 +1,48 @@
+# SecureCam codebase architecture
+
+```mermaid
+flowchart LR
+  CAMERA["Camera device
+  Mobile camera app / browser simulator"]:::client
+
+  USER["User devices
+  Web app / mobile app"]:::client
+
+  subgraph PLATFORM["SecureCam platform"]
+    BACKEND["Backend service
+    • authentication
+    • device coordination
+    • live stream control
+    • motion events
+    • recordings access"]:::backend
+  end
+
+  DATA["Core data layer
+  PostgreSQL"]:::data
+
+  MEDIA["Media storage
+  MinIO / S3-compatible object storage"]:::data
+
+  NOTIFY["Notifications
+  push + in-app activity updates"]:::service
+
+  CAMERA -->|"motion, stream, recordings"| BACKEND
+  USER -->|"auth, viewing, control"| BACKEND
+
+  BACKEND -->|"app state, users, devices, events"| DATA
+  BACKEND -->|"video and recording assets"| MEDIA
+  BACKEND -->|"alerts and activity fan-out"| NOTIFY
+
+  NOTIFY --> USER
+
+  classDef client fill:#e8f1ff,stroke:#3b82f6,stroke-width:2px,color:#111827;
+  classDef backend fill:#ecfdf3,stroke:#16a34a,stroke-width:2px,color:#111827;
+  classDef data fill:#fff7e8,stroke:#f59e0b,stroke-width:2px,color:#111827;
+  classDef service fill:#f3e8ff,stroke:#9333ea,stroke-width:2px,color:#111827;
+```
+
+## Notes
+
+- This version is intentionally high level.
+- It treats the web app, mobile app, and simulator as client surfaces around one backend platform.
+- Internal backend modules such as routes, workers, realtime gateway, and media scaffolding are abstracted into a single service block.

docs/database-schema-diagram.md

@@ -0,0 +1,218 @@
+# SecureCam database schema
+
+```mermaid
+erDiagram
+    USERS {
+        uuid id PK
+        varchar email UK
+        varchar name
+        varchar password_hash
+        boolean email_verified
+        text image
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    DEVICES {
+        uuid id PK
+        uuid user_id FK
+        varchar name
+        varchar role
+        varchar platform
+        varchar app_version
+        text push_token
+        varchar status
+        boolean is_camera
+        timestamp last_seen_at
+        timestamp updated_at
+        timestamp created_at
+    }
+
+    DEVICE_LINKS {
+        uuid id PK
+        uuid owner_user_id FK
+        uuid camera_device_id FK
+        uuid client_device_id FK
+        varchar status
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    COMMANDS {
+        uuid id PK
+        uuid owner_user_id FK
+        uuid source_device_id FK
+        uuid target_device_id FK
+        varchar command_type
+        jsonb payload
+        varchar status
+        integer retry_count
+        timestamp last_dispatched_at
+        timestamp acknowledged_at
+        text error
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    STREAM_SESSIONS {
+        uuid id PK
+        uuid owner_user_id FK
+        uuid camera_device_id FK
+        uuid requester_device_id FK
+        varchar status
+        varchar reason
+        varchar media_provider
+        varchar media_session_id
+        text publish_endpoint
+        text subscribe_endpoint
+        varchar stream_key
+        timestamp started_at
+        timestamp ended_at
+        jsonb metadata
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    RECORDINGS {
+        uuid id PK
+        uuid owner_user_id FK
+        uuid stream_session_id FK
+        uuid camera_device_id FK
+        uuid requester_device_id FK
+        uuid event_id FK
+        varchar object_key
+        varchar bucket
+        integer duration_seconds
+        integer size_bytes
+        varchar status
+        timestamp available_at
+        text error
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    EVENTS {
+        uuid id PK
+        uuid user_id FK
+        uuid device_id FK
+        varchar title
+        varchar triggered_by
+        varchar status
+        timestamp started_at
+        timestamp ended_at
+        timestamp notified_at
+        varchar video_url UK
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    NOTIFICATIONS {
+        uuid id PK
+        uuid event_id FK
+        uuid user_id FK
+        timestamp sent_at
+        varchar channel
+        varchar status
+        boolean is_read
+    }
+
+    NOTIFICATION_DELIVERIES {
+        uuid id PK
+        uuid owner_user_id FK
+        uuid recipient_device_id FK
+        varchar type
+        jsonb payload
+        varchar status
+        integer attempts
+        text last_error
+        timestamp sent_at
+        timestamp next_attempt_at
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    AUDIT_LOGS {
+        uuid id PK
+        uuid owner_user_id FK
+        uuid actor_device_id FK
+        varchar action
+        varchar target_type
+        varchar target_id
+        jsonb metadata
+        text ip_address
+        timestamp created_at
+    }
+
+    ACCOUNT {
+        uuid id PK
+        uuid user_id FK
+        text account_id
+        text provider_id
+        text access_token
+        text refresh_token
+        timestamp access_token_expires_at
+        timestamp refresh_token_expires_at
+        text id_token
+        text scope
+        text password
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    SESSION {
+        uuid id PK
+        text token UK
+        uuid user_id FK
+        timestamp expires_at
+        text ip_address
+        text user_agent
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    VERIFICATION {
+        uuid id PK
+        text identifier
+        text value
+        timestamp expires_at
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    USERS ||--o{ DEVICES : owns
+    USERS ||--o{ DEVICE_LINKS : owns
+    USERS ||--o{ COMMANDS : owns
+    USERS ||--o{ STREAM_SESSIONS : owns
+    USERS ||--o{ RECORDINGS : owns
+    USERS ||--o{ EVENTS : creates
+    USERS ||--o{ NOTIFICATIONS : receives
+    USERS ||--o{ NOTIFICATION_DELIVERIES : owns
+    USERS ||--o{ AUDIT_LOGS : owns
+    USERS ||--o{ ACCOUNT : auth_account
+    USERS ||--o{ SESSION : auth_session
+
+    DEVICES ||--o{ DEVICE_LINKS : camera_device
+    DEVICES ||--o{ DEVICE_LINKS : client_device
+    DEVICES ||--o{ COMMANDS : source_device
+    DEVICES ||--o{ COMMANDS : target_device
+    DEVICES ||--o{ STREAM_SESSIONS : camera_device
+    DEVICES ||--o{ STREAM_SESSIONS : requester_device
+    DEVICES ||--o{ RECORDINGS : camera_device
+    DEVICES ||--o{ RECORDINGS : requester_device
+    DEVICES ||--o{ EVENTS : triggers
+    DEVICES ||--o{ NOTIFICATION_DELIVERIES : recipient_device
+    DEVICES ||--o{ AUDIT_LOGS : actor_device
+
+    STREAM_SESSIONS ||--o{ RECORDINGS : produces
+    EVENTS o|--o{ RECORDINGS : may_attach
+    EVENTS ||--o{ NOTIFICATIONS : generates
+```
+
+## Notes
+
+- This is generated from the current Drizzle schema in [schema.ts](/home/matiss/Documents/Final Year Project/Backend/db/schema.ts).
+- `VERIFICATION` is currently standalone in the schema and does not reference `USERS`.
+- `DEVICE_LINKS`, `COMMANDS`, `STREAM_SESSIONS`, and `RECORDINGS` each reference `DEVICES` more than once for different roles.
+- `ACCOUNT`, `SESSION`, and `VERIFICATION` are the Better Auth support tables.
+- `recordings` now absorbs the old upload metadata responsibility that previously lived in `videos`.
+- `notification_deliveries` represents push delivery jobs, while `notifications` remains the user-facing event notification history.

docs/project-gantt-chart.md

@@ -0,0 +1,56 @@
+# SecureCam ideal project Gantt chart
+
+```mermaid
+gantt
+    title SecureCam Project Timeline
+    dateFormat  YYYY-MM-DD
+    axisFormat  %b
+    excludes    weekends
+
+    section Initiation and Planning
+    Project scoping and proposal              :done, a1, 2025-10-15, 10d
+    Requirements gathering and research       :done, a2, after a1, 12d
+    Early architecture and feasibility        :done, a3, after a1, 15d
+
+    section Initial Prototype
+    Core prototype implementation             :done, b1, 2025-10-28, 18d
+    Basic camera-to-client workflow           :done, b2, after b1, 10d
+
+    section Scope Change and Refactor
+    Major scope change identified             :milestone, m1, 2025-11-12, 0d
+    Requirements redefinition                 :crit, c1, 2025-11-13, 8d
+    Architecture redesign                     :crit, c2, after c1, 10d
+    Backend refactor and model cleanup        :crit, c3, after c2, 18d
+    Web and mobile flow realignment           :crit, c4, after c2, 14d
+
+    section Platform Rebuild
+    Authentication and device model           :d1, 2025-12-09, 12d
+    Realtime communication layer              :d2, after d1, 14d
+    Stream control and recording pipeline     :d3, after d2, 16d
+    Storage integration and signed media URLs :d4, after d1, 12d
+    Motion events and activity feed           :d5, after d2, 10d
+
+    section Client Applications
+    Web app feature completion                :e1, 2026-01-20, 18d
+    Mobile app implementation                 :e2, 2026-01-27, 24d
+    Push notifications and user feedback loop :e3, after d5, 12d
+
+    section Quality and Evaluation
+    Integration testing and bug fixing        :f1, 2026-02-24, 18d
+    Performance tuning and resilience review  :f2, after f1, 10d
+    Final validation and demo preparation     :f3, after f2, 8d
+
+    section Dissertation and Delivery
+    Documentation and architecture diagrams   :g1, 2026-03-17, 12d
+    Report writing and iteration              :g2, 2026-03-10, 26d
+    Final edits and submission prep           :g3, after g2, 8d
+    Project complete                          :milestone, m2, 2026-04-17, 0d
+```
+
+## Notes
+
+- Start date assumed: `2025-10-15` to reflect a mid-October project start.
+- Final deadline set to: `2026-04-17`.
+- The chart assumes a major scope shift in mid-November that forced the team to revisit requirements and refactor the platform.
+- The refactor is treated as a real disruption rather than a minor iteration, so the later phases are shown as a rebuild on firmer architecture rather than a straight continuation of the original prototype.
+- This is an "idealised but realistic" plan for documentation purposes, not a claim that every task happened exactly in this order.