Matiss/Final-Year-Project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(report): add section 5.3 draft assets

Browse Source
This commit is contained in:
Matiss Jurevics
2026-04-13 19:30:00 +01:00
parent 41fd7bb085
commit bd61735579
12 changed files with 1652 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/temp-section-5-3-diagrams/5.3.1-server-bootstrap.md Normal file
View File

@@ -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
```

29
docs/temp-section-5-3-diagrams/5.3.10-operational-and-support-assets.md Normal file
View File

@@ -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
```

30
docs/temp-section-5-3-diagrams/5.3.2-authentication-and-sessions.md Normal file
View File

@@ -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;
```

26
docs/temp-section-5-3-diagrams/5.3.3-device-registration-and-presence.md Normal file
View File

@@ -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
```

97
docs/temp-section-5-3-diagrams/5.3.4-database-schema-and-persistence.md Normal file
View File

@@ -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
}
```

36
docs/temp-section-5-3-diagrams/5.3.5-linking-and-control-flow.md Normal file
View File

@@ -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
```

46
docs/temp-section-5-3-diagrams/5.3.6-stream-sessions-and-signalling.md Normal file
View File

@@ -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 --> [*]
```

42
docs/temp-section-5-3-diagrams/5.3.7-motion-events-notifications-audit.md Normal file
View File

@@ -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
```

40
docs/temp-section-5-3-diagrams/5.3.8-recordings-and-object-storage.md Normal file
View File

@@ -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
```

53
docs/temp-section-5-3-diagrams/5.3.9-web-application-implementation.md Normal file
View File

@@ -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
```

18
docs/temp-section-5-3-diagrams/README.md Normal file
View File

@@ -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.