Refactor code structure for improved readability and maintainability

API.md

@@ -0,0 +1,282 @@
+# API Reference
+
+This document describes the currently implemented API surfaces in Linear Void.
+
+## Base URLs
+
+- Public app and admin: <https://linearvoid.tv>
+- WebSocket endpoint: <wss://linearvoid.tv/ws>
+- Local fallback: <http://localhost> and <ws://localhost/ws>
+
+## Authentication Model
+
+Admin REST endpoints use a cookie session.
+
+- Cookie name: linearvoid_admin_session
+- Cookie attributes: HttpOnly, SameSite=Strict, Secure when request is HTTPS (or X-Forwarded-Proto=https)
+- Session TTL: controlled by ADMIN_SESSION_TTL_HOURS (default 12h)
+
+## Chat WebSocket API
+
+### Connect
+
+Endpoint:
+
+- GET /ws?username={name}&room={room}
+
+Client sends JSON messages over the socket.
+
+### Message Envelope (client -> server)
+
+```json
+{
+  "room": "main",
+  "username": "viewer123",
+  "text": "hello world",
+  "type": "public"
+}
+```
+
+Notes:
+
+- type is usually public for room chat and private for DM room routing.
+- Private room names are formatted like dm:userA-userB (sorted usernames).
+- Moderation/system events are sent as type=system messages.
+
+### Message Envelope (server -> client)
+
+```json
+{
+  "room": "main",
+  "username": "viewer123",
+  "text": "hello world",
+  "type": "public",
+  "timestamp": "2026-08-04T12:34:56Z"
+}
+```
+
+## Admin Session API
+
+### Login
+
+- POST /api/admin/login
+- Auth: none
+
+Request:
+
+```json
+{
+  "username": "admin",
+  "password": "your-password"
+}
+```
+
+Success response:
+
+```json
+{
+  "authenticated": true,
+  "username": "admin"
+}
+```
+
+### Logout
+
+- POST /api/admin/logout
+- Auth: optional (clears cookie either way)
+
+Response:
+
+```json
+{
+  "authenticated": false
+}
+```
+
+### Session Check
+
+- GET /api/admin/session
+- Auth: cookie required
+
+Success response:
+
+```json
+{
+  "authenticated": true,
+  "username": "admin"
+}
+```
+
+Failure:
+
+- 401 unauthorized
+
+## Admin Data API
+
+All endpoints below require admin authentication.
+
+### Overview
+
+- GET /api/admin/overview
+
+Returns aggregate counters and runtime/system snapshot fields.
+
+### Playlist
+
+- GET /api/admin/playlist
+- PUT /api/admin/playlist
+
+PUT request:
+
+```json
+{
+  "content": "file '/app/media/video1.mp4'\nfile '/app/media/video2.mp4'\n"
+}
+```
+
+### Schedule
+
+- GET /api/admin/schedule
+
+Returns parsed playlist entries plus matched media metadata/runtime.
+
+### Moderation
+
+- GET /api/admin/moderation/logs?limit=50
+- POST /api/admin/moderation/actions
+
+Action request:
+
+```json
+{
+  "action": "mute",
+  "target": "username-or-id",
+  "moderator": "admin",
+  "reason": "spam",
+  "room": "main"
+}
+```
+
+### Analytics
+
+- GET /api/admin/analytics
+
+Returns totals (messages, moderation actions, rooms) and top room summary.
+
+### System
+
+- GET /api/admin/system
+
+Returns service health snapshot for chat/playout/redis/database and config metadata.
+
+### Active Users
+
+- GET /api/admin/users
+
+Returns currently discovered presence users (room + username) when Redis is available.
+
+## Media Library API
+
+### Media Collection
+
+- GET /api/admin/media
+- POST /api/admin/media (multipart upload, legacy path)
+
+Multipart form field name: file
+
+### Media Item
+
+- GET /api/admin/media/{id}
+- PUT /api/admin/media/{id}
+- DELETE /api/admin/media/{id}
+
+PUT request:
+
+```json
+{
+  "status": "ready",
+  "title": "My Clip",
+  "tags": "music,live"
+}
+```
+
+## Resumable Upload API
+
+Maximum file size: 2GB
+
+Default chunk size: 8MB
+
+### Initialize or Resume Session
+
+- POST /api/admin/media/uploads
+
+Request:
+
+```json
+{
+  "uploadId": "optional-existing-id",
+  "fileName": "clip.mp4",
+  "fileSize": 123456789,
+  "mimeType": "video/mp4",
+  "chunkSize": 8388608,
+  "totalChunks": 15
+}
+```
+
+Response:
+
+```json
+{
+  "uploadId": "hex-token",
+  "fileName": "clip.mp4",
+  "fileSize": 123456789,
+  "chunkSize": 8388608,
+  "totalChunks": 15,
+  "uploadedChunks": 3,
+  "progress": 20
+}
+```
+
+### Check Upload Status
+
+- GET /api/admin/media/uploads/{uploadId}
+
+Returns same status envelope as initialize.
+
+### Upload Chunk
+
+- PUT /api/admin/media/uploads/{uploadId}/chunk?index={chunkIndex}
+- Content-Type: application/octet-stream
+
+Response returns updated upload status envelope.
+
+### Complete Upload
+
+- POST /api/admin/media/uploads/{uploadId}/complete
+
+On success returns admin media listing payload (files + generatedAt).
+
+## Metrics and Health
+
+### Chat metrics
+
+- GET /metrics
+
+Prometheus exposition includes connected clients, stored messages, moderation actions, Redis indicators, active admin sessions, and build info.
+
+### Health
+
+- GET /health on chat service
+- GET /health on playout service
+- GET /health on nginx reverse proxy
+
+## HTTP Status Conventions
+
+- 200/201: successful request
+- 400: malformed payload, invalid input, missing required fields
+- 401: unauthorized admin request
+- 404: not found
+- 405: method not allowed
+- 409: logical conflict (for example, mismatched resumed upload)
+- 413: payload too large
+- 500: internal server error