# nxdun/rust-codebase architecture

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

- Interactive diagram: https://gitdiagram.com/nxdun/rust-codebase
- Repository: https://github.com/nxdun/rust-codebase

## Overview

1. **Overall shape**
   - This is a Rust backend API service with a classic layered layout: HTTP entrypoints, request middleware, controllers, services, and models.
   - The main business capability is a yt-dlp-based media download API, wrapped with security controls and job handling.

2. **Runtime entrypoint and composition**
   - `src/main.rs` starts the application.
   - `src/app.rs`, `src/config.rs`, and `src/state.rs` are the composition layer: they assemble configuration, shared runtime state, and server wiring before requests are served.

3. **HTTP boundary and routing**
   - `src/routes/` defines endpoint groups, split into health, validation, root, and API v1 routes.
   - `src/controllers/` contains the request handlers that map HTTP requests to domain actions.
   - The API is versioned under `src/routes/api/v1/` and `src/controllers/api/v1/`, which is the main public surface for the yt-dlp features.

4. **Primary request flow**
   - A request enters the router, passes through middleware, then reaches a controller.
   - Controllers call into services for actual work, and return typed models from `src/models/`.
   - This keeps HTTP concerns separate from media-processing logic.

5. **Security and abuse controls**
   - `src/middleware/` contains cross-cutting protections:
     - CORS handling
     - IP-based rate limiting
     - CAPTCHA verification
     - authentication-related checks
   - `src/controllers/validation_controller.rs` and `src/extractors/validated_json.rs` indicate that some endpoints require explicit request validation before business logic runs.

6. **yt-dlp subsystem**
   - `src/services/ytdlp/` is the core domain service layer.
   - The exposed endpoints in `src/controllers/api/v1/ytdlp_controller.rs` and `src/routes/api/v1/ytdlp_routes.rs` cover job submission, job lookup, progress streaming, file download, and supported-site discovery.
   - The README notes acceleration via `aria2c`, so the download workflow is not just a simple subprocess wrapper; it is tuned for throughput.

7. **State, persistence, and runtime coordination**
   - `src/db/postgres.rs` and `src/db/redis.rs` show two backend dependencies with distinct roles.
   - Redis is the likely fit for ephemeral coordination such as rate limiting, job state, or short-lived caches.
   - Postgres is the likely durable store for job or user-related records.
   - The README’s mention of DashMap, weak references, and Tokio semaphores suggests in-memory concurrency control and lifecycle management around the job subsystem.

8. **Data contracts**
   - `src/models/health_model.rs`, `validation_model.rs`, and `ytdlp_model.rs` define the request/response payloads used at the API boundary.
   - These models are the contract between controllers and clients, and likely also the serialization shape for persistence and job state.

9. **Error handling**
   - `src/error.rs` and `src/controllers/error_controller.rs` centralize failure handling.
   - This indicates the API has a consistent error translation layer rather than ad hoc per-handler responses.

10. **Operational endpoints**
   - Health and root handlers exist separately from the v1 API, which is typical for readiness/liveness checks and a basic service landing endpoint.
   - The Postman collection includes explicit health, root, validation, and yt-dlp scenarios, so these are intended public entrypoints, not internal-only utilities.

11. **Infrastructure and deployment**
   - The repo includes full Terraform under `infra/digitalocean/`, targeting DigitalOcean droplets and volumes.
   - Cloudflare is used for Terraform remote state backend and DNS-related resources.
   - `infra/common/cloud-init.template` shows first-boot provisioning for the VM, likely to install Docker and launch the containerized service.
   - This means the production boundary is VM-based container deployment, not a serverless or Kubernetes architecture.

12. **Container and local development path**
   - `Dockerfile`, `Dockerfile.dev`, `docker-compose.yml`, and `docker-compose.dev.yml` support both production and local multi-service runs.
   - `Caddyfile.local` suggests a local reverse-proxy layer for dev-time routing/TLS or host-based access.
   - `docker-entrypoint.sh` is part of startup orchestration inside the container.

13. **Validation and test strategy**
   - `tests/api/` contains integration-style API tests for the main endpoint groups.
   - The `postman/` directory provides a request collection for manual validation and API exploration.
   - CI in `.github/workflows/` runs Rust linting, tests, and builds, so the architecture is guarded by automated verification rather than only runtime monitoring.

14. **What to draw in an architecture diagram**
   - The main boxes should be: external client → HTTP routes/controllers → middleware → yt-dlp service layer → Redis/Postgres/shared state → external yt-dlp/aria2c process.
   - Add separate boxes for security middleware, error handling, and infrastructure provisioning on DigitalOcean with Terraform/Caddy/Docker around the application.

Main entry points: [`src/routes/mod.rs`](https://github.com/nxdun/rust-codebase/blob/main/src/routes/mod.rs) (routes), [`src/controllers/mod.rs`](https://github.com/nxdun/rust-codebase/blob/main/src/controllers/mod.rs) (controllers), [`src/middleware/mod.rs`](https://github.com/nxdun/rust-codebase/blob/main/src/middleware/mod.rs) (middleware), [`src/app.rs`](https://github.com/nxdun/rust-codebase/blob/main/src/app.rs) (app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("main<br/>entrypoint<br/>[main.rs]"))
  node_app["app<br/>composition<br/>[app.rs]"]
  node_config["config<br/>settings<br/>[config.rs]"]
  node_state[("state<br/>[state.rs]")]
end

subgraph group_http["HTTP API"]
  node_routes["routes<br/>router<br/>[mod.rs]"]
  node_api_v1_routes["v1 routes<br/>api routes<br/>[mod.rs]"]
  node_health_routes["health routes<br/>route group<br/>[health_routes.rs]"]
  node_validation_routes["validation routes<br/>route group"]
  node_ytdlp_routes["ytdlp routes<br/>route group<br/>[ytdlp_routes.rs]"]
  node_middleware["middleware<br/>cross-cutting<br/>[mod.rs]"]
  node_auth["auth<br/>middleware<br/>[auth.rs]"]
  node_captcha["captcha<br/>middleware<br/>[captcha.rs]"]
  node_rate_limit["rate limit<br/>middleware<br/>[rate_limit.rs]"]
  node_cors["cors<br/>middleware<br/>[cors.rs]"]
  node_controllers["controllers<br/>handler layer<br/>[mod.rs]"]
  node_ytdlp_controller["ytdlp ctl<br/>api handler"]
  node_validation_controller["validation ctl<br/>api handler"]
  node_error_controller["error ctl<br/>error handler"]
  node_health_controller["health ctl<br/>status handler"]
  node_root_controller["root ctl<br/>landing handler<br/>[root_controller.rs]"]
  node_validated_json["validated json<br/>extractor<br/>[validated_json.rs]"]
  node_models["models<br/>contracts<br/>[mod.rs]"]
  node_error["error<br/>[error.rs]"]
end

subgraph group_domain["YTDLP Domain"]
  node_ytdlp_service["ytdlp svc<br/>domain service<br/>[mod.rs]"]
end

subgraph group_data["Data Layer"]
  node_postgres[("postgres<br/>database<br/>[postgres.rs]")]
  node_redis[("redis<br/>cache/coordination<br/>[redis.rs]")]
end

subgraph group_infra["Infrastructure"]
  node_docker["docker<br/>container runtime"]
  node_compose["compose<br/>local stack<br/>[docker-compose.yml]"]
  node_terraform["terraform<br/>provisioning<br/>[provider.tf]"]
  node_cloud_init["cloud-init<br/>boot config"]
end

node_main -->|"starts"| node_app
node_app -->|"loads"| node_config
node_app -->|"builds"| node_state
node_app -->|"wires"| node_routes
node_routes -->|"includes"| node_health_routes
node_routes -->|"includes"| node_validation_routes
node_routes -->|"includes"| node_api_v1_routes
node_api_v1_routes -->|"maps"| node_ytdlp_routes
node_routes -->|"dispatches to"| node_controllers
node_controllers -->|"uses"| node_health_controller
node_controllers -->|"uses"| node_root_controller
node_controllers -->|"uses"| node_validation_controller
node_controllers -->|"uses"| node_ytdlp_controller
node_controllers -->|"uses"| node_error_controller
node_ytdlp_controller -->|"calls"| node_ytdlp_service
node_ytdlp_controller -->|"returns"| node_models
node_validation_controller -->|"requires"| node_validated_json
node_validation_controller -->|"returns"| node_models
node_health_controller -->|"returns"| node_models
node_ytdlp_service -->|"persists"| node_postgres
node_ytdlp_service -->|"coordinates"| node_redis
node_ytdlp_service -->|"shares"| node_state
node_routes -->|"passes through"| node_middleware
node_middleware -->|"includes"| node_cors
node_middleware -->|"includes"| node_rate_limit
node_middleware -->|"includes"| node_captcha
node_middleware -->|"includes"| node_auth
node_docker -->|"supports"| node_compose
node_compose -->|"boots"| node_cloud_init
node_terraform -->|"provisions"| node_cloud_init
node_terraform -->|"deploys"| node_docker
node_error_controller -->|"translates"| node_error

click node_main "https://github.com/nxdun/rust-codebase/blob/main/src/main.rs"
click node_app "https://github.com/nxdun/rust-codebase/blob/main/src/app.rs"
click node_config "https://github.com/nxdun/rust-codebase/blob/main/src/config.rs"
click node_state "https://github.com/nxdun/rust-codebase/blob/main/src/state.rs"
click node_routes "https://github.com/nxdun/rust-codebase/blob/main/src/routes/mod.rs"
click node_api_v1_routes "https://github.com/nxdun/rust-codebase/blob/main/src/routes/api/v1/mod.rs"
click node_health_routes "https://github.com/nxdun/rust-codebase/blob/main/src/routes/health_routes.rs"
click node_validation_routes "https://github.com/nxdun/rust-codebase/blob/main/src/routes/validation_routes.rs"
click node_ytdlp_routes "https://github.com/nxdun/rust-codebase/blob/main/src/routes/api/v1/ytdlp_routes.rs"
click node_middleware "https://github.com/nxdun/rust-codebase/blob/main/src/middleware/mod.rs"
click node_auth "https://github.com/nxdun/rust-codebase/blob/main/src/middleware/auth.rs"
click node_captcha "https://github.com/nxdun/rust-codebase/blob/main/src/middleware/captcha.rs"
click node_rate_limit "https://github.com/nxdun/rust-codebase/blob/main/src/middleware/rate_limit.rs"
click node_cors "https://github.com/nxdun/rust-codebase/blob/main/src/middleware/cors.rs"
click node_controllers "https://github.com/nxdun/rust-codebase/blob/main/src/controllers/mod.rs"
click node_ytdlp_controller "https://github.com/nxdun/rust-codebase/blob/main/src/controllers/api/v1/ytdlp_controller.rs"
click node_validation_controller "https://github.com/nxdun/rust-codebase/blob/main/src/controllers/validation_controller.rs"
click node_error_controller "https://github.com/nxdun/rust-codebase/blob/main/src/controllers/error_controller.rs"
click node_health_controller "https://github.com/nxdun/rust-codebase/blob/main/src/controllers/health_controller.rs"
click node_root_controller "https://github.com/nxdun/rust-codebase/blob/main/src/controllers/root_controller.rs"
click node_validated_json "https://github.com/nxdun/rust-codebase/blob/main/src/extractors/validated_json.rs"
click node_models "https://github.com/nxdun/rust-codebase/blob/main/src/models/mod.rs"
click node_ytdlp_service "https://github.com/nxdun/rust-codebase/blob/main/src/services/ytdlp/mod.rs"
click node_postgres "https://github.com/nxdun/rust-codebase/blob/main/src/db/postgres.rs"
click node_redis "https://github.com/nxdun/rust-codebase/blob/main/src/db/redis.rs"
click node_error "https://github.com/nxdun/rust-codebase/blob/main/src/error.rs"
click node_docker "https://github.com/nxdun/rust-codebase/tree/main/Dockerfile"
click node_compose "https://github.com/nxdun/rust-codebase/blob/main/docker-compose.yml"
click node_terraform "https://github.com/nxdun/rust-codebase/blob/main/infra/digitalocean/components/provider.tf"
click node_cloud_init "https://github.com/nxdun/rust-codebase/blob/main/infra/common/cloud-init.template"

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_main,node_app,node_config,node_state toneBlue
class node_routes,node_api_v1_routes,node_health_routes,node_validation_routes,node_ytdlp_routes,node_middleware,node_auth,node_captcha,node_rate_limit,node_cors,node_controllers,node_ytdlp_controller,node_validation_controller,node_error_controller,node_health_controller,node_root_controller,node_validated_json,node_models,node_error toneAmber
class node_ytdlp_service toneMint
class node_postgres,node_redis toneRose
class node_docker,node_compose,node_terraform,node_cloud_init toneIndigo
```

## Components

### Runtime

Application startup, config, and shared state

- [main](https://github.com/nxdun/rust-codebase/blob/main/src/main.rs): entrypoint · Application entrypoint · `src/main.rs`
- [app](https://github.com/nxdun/rust-codebase/blob/main/src/app.rs): composition · Wires server components · `src/app.rs`
- [config](https://github.com/nxdun/rust-codebase/blob/main/src/config.rs): settings · Loads runtime settings · `src/config.rs`
- [state](https://github.com/nxdun/rust-codebase/blob/main/src/state.rs): shared state · Runtime state and handles · `src/state.rs`

### HTTP API

Routes, controllers, middleware, and request contracts

- [routes](https://github.com/nxdun/rust-codebase/blob/main/src/routes/mod.rs): router · Top-level route assembly · `src/routes/mod.rs`
- [v1 routes](https://github.com/nxdun/rust-codebase/blob/main/src/routes/api/v1/mod.rs): api routes · Versioned public API routing · `src/routes/api/v1/mod.rs`
- [health routes](https://github.com/nxdun/rust-codebase/blob/main/src/routes/health_routes.rs): route group · Liveness and readiness endpoints · `src/routes/health_routes.rs`
- [validation routes](https://github.com/nxdun/rust-codebase/blob/main/src/routes/validation_routes.rs): route group · Explicit request validation endpoints · `src/routes/validation_routes.rs`
- [ytdlp routes](https://github.com/nxdun/rust-codebase/blob/main/src/routes/api/v1/ytdlp_routes.rs): route group · Download and job endpoints · `src/routes/api/v1/ytdlp_routes.rs`
- [middleware](https://github.com/nxdun/rust-codebase/blob/main/src/middleware/mod.rs): cross-cutting · HTTP-wide request protections · `src/middleware/mod.rs`
- [auth](https://github.com/nxdun/rust-codebase/blob/main/src/middleware/auth.rs): middleware · Authentication checks · `src/middleware/auth.rs`
- [captcha](https://github.com/nxdun/rust-codebase/blob/main/src/middleware/captcha.rs): middleware · CAPTCHA verification · `src/middleware/captcha.rs`
- [rate limit](https://github.com/nxdun/rust-codebase/blob/main/src/middleware/rate_limit.rs): middleware · IP-based throttling · `src/middleware/rate_limit.rs`
- [cors](https://github.com/nxdun/rust-codebase/blob/main/src/middleware/cors.rs): middleware · Cross-origin policy · `src/middleware/cors.rs`
- [controllers](https://github.com/nxdun/rust-codebase/blob/main/src/controllers/mod.rs): handler layer · HTTP handlers and translation layer · `src/controllers/mod.rs`
- [ytdlp ctl](https://github.com/nxdun/rust-codebase/blob/main/src/controllers/api/v1/ytdlp_controller.rs): api handler · YT-DLP job and file handlers · `src/controllers/api/v1/ytdlp_controller.rs`
- [validation ctl](https://github.com/nxdun/rust-codebase/blob/main/src/controllers/validation_controller.rs): api handler · Validation gate handlers · `src/controllers/validation_controller.rs`
- [error ctl](https://github.com/nxdun/rust-codebase/blob/main/src/controllers/error_controller.rs): error handler · Unified API error responses · `src/controllers/error_controller.rs`
- [health ctl](https://github.com/nxdun/rust-codebase/blob/main/src/controllers/health_controller.rs): status handler · Health response logic · `src/controllers/health_controller.rs`
- [root ctl](https://github.com/nxdun/rust-codebase/blob/main/src/controllers/root_controller.rs): landing handler · Basic service landing response · `src/controllers/root_controller.rs`
- [validated json](https://github.com/nxdun/rust-codebase/blob/main/src/extractors/validated_json.rs): extractor · Prevalidated JSON request extractor · `src/extractors/validated_json.rs`
- [models](https://github.com/nxdun/rust-codebase/blob/main/src/models/mod.rs): contracts · API payload definitions · `src/models/mod.rs`
- [error](https://github.com/nxdun/rust-codebase/blob/main/src/error.rs): error types · Central error definitions · `src/error.rs`

### YTDLP Domain

Media download job orchestration and external process flow

- [ytdlp svc](https://github.com/nxdun/rust-codebase/blob/main/src/services/ytdlp/mod.rs): domain service · Job orchestration and download workflow · `src/services/ytdlp/mod.rs`

### Data Layer

Persistent and ephemeral backing stores

- [postgres](https://github.com/nxdun/rust-codebase/blob/main/src/db/postgres.rs): database · Durable persistence · `src/db/postgres.rs`
- [redis](https://github.com/nxdun/rust-codebase/blob/main/src/db/redis.rs): cache/coordination · Ephemeral coordination and caching · `src/db/redis.rs`

### Infrastructure

Container, deployment, and provisioning layer

- [docker](https://github.com/nxdun/rust-codebase/tree/main/Dockerfile): container runtime · Container build and startup · `Dockerfile`
- [compose](https://github.com/nxdun/rust-codebase/blob/main/docker-compose.yml): local stack · Local multi-service orchestration · `docker-compose.yml`
- [terraform](https://github.com/nxdun/rust-codebase/blob/main/infra/digitalocean/components/provider.tf): provisioning · DigitalOcean deployment infrastructure · `infra/digitalocean/components/provider.tf`
- [cloud-init](https://github.com/nxdun/rust-codebase/blob/main/infra/common/cloud-init.template): boot config · VM first-boot provisioning · `infra/common/cloud-init.template`

## Connections

- main → app: starts · Bootstraps application composition
- app → config: loads · Reads runtime configuration
- app → state: builds · Creates shared runtime state
- app → routes: wires · Installs routing tree
- routes → health routes: includes · Public health endpoints
- routes → validation routes: includes · Validation endpoints
- routes → v1 routes: includes · Versioned API subtree
- v1 routes → ytdlp routes: maps · YT-DLP API surface
- routes → controllers: dispatches to · Routes terminate in handlers
- controllers → health ctl: uses · Health handling
- controllers → root ctl: uses · Landing page handling
- controllers → validation ctl: uses · Validation gate handling
- controllers → ytdlp ctl: uses · Main download handlers
- controllers → error ctl: uses · Shared error translation
- ytdlp ctl → ytdlp svc: calls · Delegates download job work
- ytdlp ctl → models: returns · Serializes API payloads
- validation ctl → validated json: requires · Validated request extraction
- validation ctl → models: returns · Validation response contracts
- health ctl → models: returns · Health response contract
- ytdlp svc → postgres: persists · Stores durable job data
- ytdlp svc → redis: coordinates · Uses ephemeral coordination
- ytdlp svc → state: shares · Uses app-managed concurrency and handles
- routes → middleware: passes through · Request middleware pipeline
- middleware → cors: includes · Cross-origin control
- middleware → rate limit: includes · Throttling control
- middleware → captcha: includes · Bot defense
- middleware → auth: includes · Auth-related checks
- docker → compose: supports · Production and local containerization
- compose → cloud-init: boots · VM or container startup path
- terraform → cloud-init: provisions · DigitalOcean VM initialization
- terraform → docker: deploys · Runs service on provisioned host
- error ctl → error: translates · Maps internal errors to API responses
