# ritikkumar27/media-force architecture

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

- Interactive diagram: https://gitdiagram.com/ritikkumar27/media-force
- Repository: https://github.com/ritikkumar27/media-force

## Overview

MediaForce accepts authenticated requests to register/login, submit media URLs, inspect download status, and retrieve completed files. Its API persists download ownership and queues work for a background yt-dlp processor; progress is bridged to clients over WebSockets. The web tree shows login, registration, and dashboard surfaces, but the sampled Astro config and pages do not show API or socket calls. Queue, database, security, worker, and realtime links are drawn where README documentation or indexed source references support them; unshown web wiring is omitted.

Main entry points: [`apps/api/src/downloads/downloads.controller.ts`](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.controller.ts) (Download routes), [`apps/api/src/downloads/downloads.service.ts`](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.service.ts) (Download service), [`apps/api/src/app.module.ts`](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/app.module.ts) (App wiring), [`apps/api/src/downloads/downloads.processor.ts`](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.processor.ts) (Download worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_web["Web pages"]
  node_shared["Shared package<br/>[index.ts]"]
end

subgraph group_identity["Identity and access"]
  node_authhttp["Auth routes<br/>[auth.controller.ts]"]
  node_authlogic["JWT auth<br/>[auth.service.ts]"]
  node_authdto["Auth validation<br/>[auth.dto.ts]"]
  node_users["User accounts<br/>[users.service.ts]"]
  node_userstore[("User records<br/>[user.entity.ts]")]
  node_httpguard["HTTP guard<br/>[auth.guard.ts]"]
  node_ws_guard["Socket guard<br/>[ws.guard.ts]"]
end

subgraph group_downloads["Download workflow"]
  node_downloadhttp["Download routes"]
  node_downloadlogic["Download service"]
  node_downloadstore[("Download records<br/>[download.entity.ts]")]
  node_queue["Job queue"]
  node_worker["Download worker"]
  node_yt["yt-dlp runner<br/>[yt-dlp.service.ts]"]
  node_gateway["Progress gateway"]
end

subgraph group_runtime["API runtime"]
  node_api["API bootstrap<br/>[main.ts]"]
  node_app["App wiring<br/>[app.module.ts]"]
end

node_visitor(("User"))
node_redis[("Redis")]
node_postgres[("PostgreSQL")]
node_socketclient(("Socket client"))
node_media_source(("Media source"))

node_visitor -->|"uses"| node_web
node_web -.->|"imports"| node_shared
node_api -->|"starts"| node_app
node_app -->|"registers"| node_authhttp
node_app -->|"registers"| node_downloadhttp
node_app -->|"registers"| node_users
node_authhttp -->|"delegates"| node_authlogic
node_authhttp -->|"validates with"| node_authdto
node_authlogic -->|"looks up / creates"| node_users
node_users -->|"persists"| node_userstore
node_downloadhttp -->|"guards requests"| node_httpguard
node_downloadhttp -->|"delegates"| node_downloadlogic
node_downloadlogic -->|"reads / writes"| node_downloadstore
node_downloadlogic -->|"enqueues jobs"| node_queue
node_queue -->|"stores jobs"| node_redis
node_worker -->|"runs downloads"| node_yt
node_worker -->|"updates status"| node_downloadstore
node_worker -.->|"publishes progress"| node_gateway
node_gateway -->|"secures handshake"| node_ws_guard
node_gateway -->|"broadcasts progress"| node_socketclient
node_downloadlogic -->|"fetches metadata"| node_yt
node_downloadhttp -->|"streams completed file"| node_visitor
node_yt -->|"downloads from"| node_media_source
node_downloadstore -->|"persists records"| node_postgres

click node_web "https://github.com/ritikkumar27/media-force/tree/main/apps/web/src/pages"
click node_shared "https://github.com/ritikkumar27/media-force/blob/main/packages/shared/index.ts"
click node_api "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/main.ts"
click node_app "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/app.module.ts"
click node_authhttp "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/auth.controller.ts"
click node_authlogic "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/auth.service.ts"
click node_authdto "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/dto/auth.dto.ts"
click node_users "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/users/users.service.ts"
click node_userstore "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/users/entities/user.entity.ts"
click node_httpguard "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/auth.guard.ts"
click node_ws_guard "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/ws.guard.ts"
click node_downloadhttp "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.controller.ts"
click node_downloadlogic "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.service.ts"
click node_downloadstore "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/entities/download.entity.ts"
click node_worker "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.processor.ts"
click node_yt "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/yt-dlp/yt-dlp.service.ts"
click node_gateway "https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads/downloads.gateway.ts"

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_web,node_shared,node_visitor,node_socketclient toneBlue
class node_authhttp,node_authlogic,node_authdto,node_users,node_userstore,node_httpguard,node_ws_guard,node_redis,node_postgres toneAmber
class node_downloadhttp,node_downloadlogic,node_downloadstore,node_queue,node_worker,node_yt,node_gateway toneMint
class node_api,node_app toneRose
class node_media_source toneIndigo
```

## Components

### Web application

- [Web pages](https://github.com/ritikkumar27/media-force/tree/main/apps/web/src/pages): `apps/web/src/pages`
- [Shared package](https://github.com/ritikkumar27/media-force/blob/main/packages/shared/index.ts): `packages/shared/index.ts`

### Identity and access

- [Auth routes](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/auth.controller.ts): `apps/api/src/auth/auth.controller.ts`
- [JWT auth](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/auth.service.ts): `apps/api/src/auth/auth.service.ts`
- [Auth validation](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/dto/auth.dto.ts): `apps/api/src/auth/dto/auth.dto.ts`
- [User accounts](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/users/users.service.ts): `apps/api/src/users/users.service.ts`
- [User records](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/users/entities/user.entity.ts): `apps/api/src/users/entities/user.entity.ts`
- [HTTP guard](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/auth.guard.ts): `apps/api/src/auth/auth.guard.ts`
- [Socket guard](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/auth/ws.guard.ts): `apps/api/src/auth/ws.guard.ts`

### Download workflow

- [Download routes](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.controller.ts): `apps/api/src/downloads/downloads.controller.ts`
- [Download service](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.service.ts): `apps/api/src/downloads/downloads.service.ts`
- [Download records](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/entities/download.entity.ts): `apps/api/src/downloads/entities/download.entity.ts`
- **Job queue**
- [Download worker](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads.processor.ts): `apps/api/src/downloads/downloads.processor.ts`
- [yt-dlp runner](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/yt-dlp/yt-dlp.service.ts): `apps/api/src/downloads/yt-dlp/yt-dlp.service.ts`
- [Progress gateway](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/downloads/downloads/downloads.gateway.ts): `apps/api/src/downloads/downloads/downloads.gateway.ts`

### API runtime

- [API bootstrap](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/main.ts): `apps/api/src/main.ts`
- [App wiring](https://github.com/ritikkumar27/media-force/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`

### Other components

- **User**
- **Redis**
- **PostgreSQL**
- **Socket client**
- **Media source**

## Connections

- User → Web pages: uses (evidence: `README.md`)
- Web pages → Shared package: imports
- API bootstrap → App wiring: starts (evidence: `apps/api/src/main.ts`)
- App wiring → Auth routes: registers (evidence: `apps/api/src/app.module.ts`)
- App wiring → Download routes: registers (evidence: `apps/api/src/app.module.ts`)
- App wiring → User accounts: registers (evidence: `apps/api/src/app.module.ts`)
- Auth routes → JWT auth: delegates (evidence: `apps/api/src/auth/auth.controller.ts`)
- Auth routes → Auth validation: validates with (evidence: `apps/api/src/auth/auth.controller.ts`)
- JWT auth → User accounts: looks up / creates (evidence: `apps/api/src/auth/auth.service.ts`)
- User accounts → User records: persists (evidence: `apps/api/src/users/users.service.ts`)
- Download routes → HTTP guard: guards requests (evidence: `apps/api/src/downloads/downloads.controller.ts`)
- Download routes → Download service: delegates (evidence: `apps/api/src/downloads/downloads.controller.ts`)
- Download service → Download records: reads / writes (evidence: `apps/api/src/downloads/downloads.service.ts`)
- Download service → Job queue: enqueues jobs (evidence: `apps/api/src/downloads/downloads.service.ts`)
- Job queue → Redis: stores jobs (evidence: `README.md`)
- Download worker → yt-dlp runner: runs downloads (evidence: `apps/api/src/downloads/downloads.processor.ts`)
- Download worker → Download records: updates status (evidence: `apps/api/src/downloads/downloads.processor.ts`)
- Download worker → Progress gateway: publishes progress
- Progress gateway → Socket guard: secures handshake (evidence: `apps/api/src/downloads/downloads/downloads.gateway.ts`)
- Progress gateway → Socket client: broadcasts progress (evidence: `README.md`)
- Download service → yt-dlp runner: fetches metadata (evidence: `apps/api/src/downloads/downloads.service.ts`)
- Download routes → User: streams completed file (evidence: `apps/api/src/downloads/downloads.controller.ts`)
- yt-dlp runner → Media source: downloads from (evidence: `apps/api/src/downloads/yt-dlp/yt-dlp.service.ts`)
- Download records → PostgreSQL: persists records (evidence: `README.md`)