# somnath516/streambox architecture

> Architecture diagram of the GitHub repository somnath516/streambox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/somnath516/streambox
- Repository: https://github.com/somnath516/streambox

## Overview

StreamBox is a movie catalog and streaming application with an administrative upload and management workflow. Users browse movie records and request media; administrators authenticate to upload or edit titles, while the backend stores catalog metadata and serves video and related assets. The graph reflects the sampled routes and server wiring. Frontend-to-API behavior and some documented-by-structure features are not shown in excerpts, so those connections are marked unverified rather than asserted.

Main entry points: [`backend/server.js`](https://github.com/somnath516/streambox/blob/main/backend/server.js) (Express server), [`backend/routes/upload.routes.js`](https://github.com/somnath516/streambox/blob/main/backend/routes/upload.routes.js) (Upload routes), [`backend/routes/movies.routes.js`](https://github.com/somnath516/streambox/blob/main/backend/routes/movies.routes.js) (Movie routes), [`backend/services/db.service.js`](https://github.com/somnath516/streambox/blob/main/backend/services/db.service.js) (Movie catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_frontend["Web interface<br/>[index.js]"]
  node_player["Playback UI<br/>[player.html]"]
end

subgraph group_http["HTTP application"]
  node_server["Express server<br/>[server.js]"]
  node_movies_api["Movie routes<br/>[movies.routes.js]"]
  node_upload_api["Upload routes<br/>[upload.routes.js]"]
  node_media_api["Media routes<br/>[media.routes.js]"]
  node_health_api["Health routes<br/>[health.routes.js]"]
  node_control_api["Control routes<br/>[control.routes.js]"]
  node_auth["Admin authentication<br/>[auth.js]"]
end

subgraph group_catalog["Catalog and media"]
  node_catalog_db[("Movie catalog<br/>[db.service.js]")]
  node_upload_service["Upload handling<br/>[upload.service.js]"]
  node_upload_sessions["Upload sessions"]
  node_media_service["Media streaming<br/>[media.service.js]"]
  node_subtitle["Subtitle validation<br/>[subtitle.js]"]
end

subgraph group_operations["Runtime support"]
  node_config["Runtime configuration<br/>[config.service.js]"]
  node_errors["Error responses<br/>[errorContract.js]"]
  node_logger["Application logging<br/>[logger.js]"]
  node_async["Async route wrapper<br/>[asyncHandler.js]"]
end

node_viewer(("Viewer"))
node_admin(("Administrator"))

node_viewer -.->|"browses"| node_frontend
node_admin -.->|"manages titles"| node_frontend
node_frontend -.->|"calls API"| node_server
node_player -.->|"requests media"| node_media_api
node_server -->|"loads settings"| node_config
node_server -->|"initializes database"| node_catalog_db
node_server -->|"mounts routes"| node_movies_api
node_server -->|"mounts routes"| node_upload_api
node_server -->|"mounts routes"| node_health_api
node_server -->|"mounts routes"| node_media_api
node_server -->|"mounts routes"| node_control_api
node_movies_api -->|"reads and updates"| node_catalog_db
node_movies_api -->|"protects mutations"| node_auth
node_movies_api -->|"wraps handlers"| node_async
node_movies_api -->|"sends errors"| node_errors
node_upload_api -->|"protects uploads"| node_auth
node_upload_api -->|"validates files"| node_upload_service
node_upload_api -->|"tracks sessions"| node_upload_sessions
node_upload_api -.->|"stores movie"| node_catalog_db
node_upload_api -->|"wraps handlers"| node_async
node_upload_api -->|"sends errors"| node_errors
node_upload_service -->|"validates subtitles"| node_subtitle
node_upload_service -->|"registers files"| node_upload_sessions
node_media_api -->|"streams requests"| node_media_service
node_health_api -->|"reports settings"| node_config
node_health_api -->|"wraps handlers"| node_async
node_health_api -->|"uses error contract"| node_errors
node_auth -->|"logs decisions"| node_logger
node_errors -->|"logs failures"| node_logger
node_catalog_db -->|"uses data paths"| node_config
node_catalog_db -->|"logs diagnostics"| node_logger

click node_frontend "https://github.com/somnath516/streambox/blob/main/frontend/index.js"
click node_player "https://github.com/somnath516/streambox/blob/main/frontend/player.html"
click node_server "https://github.com/somnath516/streambox/blob/main/backend/server.js"
click node_movies_api "https://github.com/somnath516/streambox/blob/main/backend/routes/movies.routes.js"
click node_upload_api "https://github.com/somnath516/streambox/blob/main/backend/routes/upload.routes.js"
click node_media_api "https://github.com/somnath516/streambox/blob/main/backend/routes/media.routes.js"
click node_health_api "https://github.com/somnath516/streambox/blob/main/backend/routes/health.routes.js"
click node_control_api "https://github.com/somnath516/streambox/blob/main/backend/routes/control.routes.js"
click node_auth "https://github.com/somnath516/streambox/blob/main/backend/middleware/auth.js"
click node_catalog_db "https://github.com/somnath516/streambox/blob/main/backend/services/db.service.js"
click node_upload_service "https://github.com/somnath516/streambox/blob/main/backend/services/upload.service.js"
click node_upload_sessions "https://github.com/somnath516/streambox/blob/main/backend/uploadSessionRegistry.js"
click node_media_service "https://github.com/somnath516/streambox/blob/main/backend/services/media.service.js"
click node_subtitle "https://github.com/somnath516/streambox/blob/main/backend/utils/subtitle.js"
click node_config "https://github.com/somnath516/streambox/blob/main/backend/services/config.service.js"
click node_errors "https://github.com/somnath516/streambox/blob/main/backend/middleware/errorContract.js"
click node_logger "https://github.com/somnath516/streambox/blob/main/backend/utils/logger.js"
click node_async "https://github.com/somnath516/streambox/blob/main/backend/utils/asyncHandler.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_player,node_viewer toneBlue
class node_server,node_movies_api,node_upload_api,node_media_api,node_health_api,node_control_api,node_auth toneAmber
class node_catalog_db,node_upload_service,node_upload_sessions,node_media_service,node_subtitle toneMint
class node_config,node_errors,node_logger,node_async toneRose
class node_admin toneIndigo
```

## Components

### Client experience

- [Web interface](https://github.com/somnath516/streambox/blob/main/frontend/index.js): `frontend/index.js`
- [Playback UI](https://github.com/somnath516/streambox/blob/main/frontend/player.html): `frontend/player.html`

### HTTP application

- [Express server](https://github.com/somnath516/streambox/blob/main/backend/server.js): `backend/server.js`
- [Movie routes](https://github.com/somnath516/streambox/blob/main/backend/routes/movies.routes.js): `backend/routes/movies.routes.js`
- [Upload routes](https://github.com/somnath516/streambox/blob/main/backend/routes/upload.routes.js): `backend/routes/upload.routes.js`
- [Media routes](https://github.com/somnath516/streambox/blob/main/backend/routes/media.routes.js): `backend/routes/media.routes.js`
- [Health routes](https://github.com/somnath516/streambox/blob/main/backend/routes/health.routes.js): `backend/routes/health.routes.js`
- [Control routes](https://github.com/somnath516/streambox/blob/main/backend/routes/control.routes.js): `backend/routes/control.routes.js`
- [Admin authentication](https://github.com/somnath516/streambox/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`

### Catalog and media

- [Movie catalog](https://github.com/somnath516/streambox/blob/main/backend/services/db.service.js): `backend/services/db.service.js`
- [Upload handling](https://github.com/somnath516/streambox/blob/main/backend/services/upload.service.js): `backend/services/upload.service.js`
- [Upload sessions](https://github.com/somnath516/streambox/blob/main/backend/uploadSessionRegistry.js): `backend/uploadSessionRegistry.js`
- [Media streaming](https://github.com/somnath516/streambox/blob/main/backend/services/media.service.js): `backend/services/media.service.js`
- [Subtitle validation](https://github.com/somnath516/streambox/blob/main/backend/utils/subtitle.js): `backend/utils/subtitle.js`

### Runtime support

- [Runtime configuration](https://github.com/somnath516/streambox/blob/main/backend/services/config.service.js): `backend/services/config.service.js`
- [Error responses](https://github.com/somnath516/streambox/blob/main/backend/middleware/errorContract.js): `backend/middleware/errorContract.js`
- [Application logging](https://github.com/somnath516/streambox/blob/main/backend/utils/logger.js): `backend/utils/logger.js`
- [Async route wrapper](https://github.com/somnath516/streambox/blob/main/backend/utils/asyncHandler.js): `backend/utils/asyncHandler.js`

### Other components

- **Viewer**
- **Administrator**

## Connections

- Viewer → Web interface: browses
- Administrator → Web interface: manages titles
- Web interface → Express server: calls API
- Playback UI → Media routes: requests media
- Express server → Runtime configuration: loads settings (evidence: `backend/server.js`)
- Express server → Movie catalog: initializes database (evidence: `backend/server.js`)
- Express server → Movie routes: mounts routes (evidence: `backend/server.js`)
- Express server → Upload routes: mounts routes (evidence: `backend/server.js`)
- Express server → Health routes: mounts routes (evidence: `backend/server.js`)
- Express server → Media routes: mounts routes (evidence: `backend/server.js`)
- Express server → Control routes: mounts routes (evidence: `backend/server.js`)
- Movie routes → Movie catalog: reads and updates (evidence: `backend/routes/movies.routes.js`)
- Movie routes → Admin authentication: protects mutations (evidence: `backend/routes/movies.routes.js`)
- Movie routes → Async route wrapper: wraps handlers (evidence: `backend/routes/movies.routes.js`)
- Movie routes → Error responses: sends errors (evidence: `backend/routes/movies.routes.js`)
- Upload routes → Admin authentication: protects uploads (evidence: `backend/routes/upload.routes.js`)
- Upload routes → Upload handling: validates files (evidence: `backend/routes/upload.routes.js`)
- Upload routes → Upload sessions: tracks sessions (evidence: `backend/routes/upload.routes.js`)
- Upload routes → Movie catalog: stores movie
- Upload routes → Async route wrapper: wraps handlers (evidence: `backend/routes/upload.routes.js`)
- Upload routes → Error responses: sends errors (evidence: `backend/routes/upload.routes.js`)
- Upload handling → Subtitle validation: validates subtitles (evidence: `backend/services/upload.service.js`)
- Upload handling → Upload sessions: registers files (evidence: `backend/services/upload.service.js`)
- Media routes → Media streaming: streams requests (evidence: `backend/routes/media.routes.js`)
- Health routes → Runtime configuration: reports settings (evidence: `backend/routes/health.routes.js`)
- Health routes → Async route wrapper: wraps handlers (evidence: `backend/routes/health.routes.js`)
- Health routes → Error responses: uses error contract (evidence: `backend/routes/health.routes.js`)
- Admin authentication → Application logging: logs decisions (evidence: `backend/middleware/auth.js`)
- Error responses → Application logging: logs failures (evidence: `backend/middleware/errorContract.js`)
- Movie catalog → Runtime configuration: uses data paths (evidence: `backend/services/db.service.js`)
- Movie catalog → Application logging: logs diagnostics (evidence: `backend/services/db.service.js`)
