# totallyle1gitaccount/media_service architecture

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

- Interactive diagram: https://gitdiagram.com/totallyle1gitaccount/media_service
- Repository: https://github.com/totallyle1gitaccount/media_service

## Overview

Media Service is a FastAPI backend for uploading, validating, processing, and managing video records. The upload route delegates to VideoService, which checks size and content, probes and validates metadata, normalizes video, and creates a database record; separate routes list, retrieve, and delete records. The README also describes PostgreSQL integration. The sampled service does not call its injected file saver, and it does not save the upload before probing the generated raw path, so no upload-to-saver link is shown. Some subsystems are represented from the README and tree rather than sampled implementation.

Main entry points: [`API/routes/videos.py`](https://github.com/totallyle1gitaccount/media_service/blob/main/API/routes/videos.py) (Video routes), [`API/core/dependencies.py`](https://github.com/totallyle1gitaccount/media_service/blob/main/API/core/dependencies.py) (Service dependencies), [`API/services/video_service.py`](https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/video_service.py) (Upload service), [`data/crud.py`](https://github.com/totallyle1gitaccount/media_service/blob/main/data/crud.py) (Video CRUD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["FastAPI app<br/>[main.py]"]
  node_video_routes["Video routes<br/>[videos.py]"]
  node_schemas["Video schemas<br/>[video_schemas.py]"]
  node_api_schemas["API schemas<br/>[api_schemas.py]"]
  node_dependencies["Service dependencies<br/>[dependencies.py]"]
end

subgraph group_processing["Video Processing"]
  node_video_service["Upload service<br/>[video_service.py]"]
  node_validator["Video validator<br/>[validation.py]"]
  node_normalizer["Probe and normalize"]
  node_path_generator["Path generator<br/>[path_generator.py]"]
  node_file_saver["File saver<br/>[file_storage.py]"]
end

subgraph group_persistence["Persistence"]
  node_video_repo["Video CRUD<br/>[crud.py]"]
  node_video_model["Video model<br/>[models.py]"]
  node_db_session["DB sessions<br/>[core.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_integrations["Media Integrations"]
  node_ffmpeg["FFmpeg / ffprobe"]
  node_libmagic["libmagic"]
  node_filesystem["Local filesystem"]
end

node_client(("API client"))

node_client -->|"HTTP requests"| node_app
node_app -->|"mounts routes"| node_video_routes
node_video_routes -->|"resolves dependencies"| node_dependencies
node_video_routes -->|"upload delegates"| node_video_service
node_video_routes -->|"CRUD calls"| node_video_repo
node_video_routes -->|"gets session"| node_db_session
node_video_routes -->|"validates responses"| node_schemas
node_video_routes -->|"deletion response"| node_api_schemas
node_dependencies -->|"constructs"| node_video_service
node_dependencies -->|"injects"| node_validator
node_dependencies -->|"injects"| node_normalizer
node_dependencies -->|"injects"| node_file_saver
node_dependencies -->|"injects"| node_video_repo
node_video_service -->|"generates paths"| node_path_generator
node_video_service -->|"validates upload"| node_validator
node_video_service -->|"probes and normalizes"| node_normalizer
node_video_service -->|"creates record"| node_video_repo
node_validator -->|"checks MIME"| node_libmagic
node_normalizer -->|"runs media tools"| node_ffmpeg
node_video_repo -->|"queries and writes"| node_video_model
node_video_repo -->|"database operations"| node_postgres
node_db_session -->|"opens sessions"| node_postgres
node_video_routes -->|"deletes video file"| node_filesystem

click node_app "https://github.com/totallyle1gitaccount/media_service/blob/main/main.py"
click node_video_routes "https://github.com/totallyle1gitaccount/media_service/blob/main/API/routes/videos.py"
click node_schemas "https://github.com/totallyle1gitaccount/media_service/blob/main/API/core/schemas/video_schemas.py"
click node_api_schemas "https://github.com/totallyle1gitaccount/media_service/blob/main/API/core/schemas/api_schemas.py"
click node_dependencies "https://github.com/totallyle1gitaccount/media_service/blob/main/API/core/dependencies.py"
click node_video_service "https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/video_service.py"
click node_validator "https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/validators/validation.py"
click node_normalizer "https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/processing/video_normalization.py"
click node_path_generator "https://github.com/totallyle1gitaccount/media_service/blob/main/API/utils/path_generator.py"
click node_file_saver "https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/file_storage.py"
click node_video_repo "https://github.com/totallyle1gitaccount/media_service/blob/main/data/crud.py"
click node_video_model "https://github.com/totallyle1gitaccount/media_service/blob/main/data/models.py"
click node_db_session "https://github.com/totallyle1gitaccount/media_service/blob/main/data/core.py"

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_app,node_video_routes,node_schemas,node_api_schemas,node_dependencies,node_client toneBlue
class node_video_service,node_validator,node_normalizer,node_path_generator,node_file_saver toneAmber
class node_video_repo,node_video_model,node_db_session,node_postgres toneMint
class node_ffmpeg,node_libmagic,node_filesystem toneRose
```

## Components

### HTTP API

- [FastAPI app](https://github.com/totallyle1gitaccount/media_service/blob/main/main.py): `main.py`
- [Video routes](https://github.com/totallyle1gitaccount/media_service/blob/main/API/routes/videos.py): `API/routes/videos.py`
- [Video schemas](https://github.com/totallyle1gitaccount/media_service/blob/main/API/core/schemas/video_schemas.py): `API/core/schemas/video_schemas.py`
- [API schemas](https://github.com/totallyle1gitaccount/media_service/blob/main/API/core/schemas/api_schemas.py): `API/core/schemas/api_schemas.py`
- [Service dependencies](https://github.com/totallyle1gitaccount/media_service/blob/main/API/core/dependencies.py): `API/core/dependencies.py`

### Video Processing

- [Upload service](https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/video_service.py): `API/services/video_service.py`
- [Video validator](https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/validators/validation.py): `API/services/validators/validation.py`
- [Probe and normalize](https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/processing/video_normalization.py): `API/services/processing/video_normalization.py`
- [Path generator](https://github.com/totallyle1gitaccount/media_service/blob/main/API/utils/path_generator.py): `API/utils/path_generator.py`
- [File saver](https://github.com/totallyle1gitaccount/media_service/blob/main/API/services/file_storage.py): `API/services/file_storage.py`

### Persistence

- [Video CRUD](https://github.com/totallyle1gitaccount/media_service/blob/main/data/crud.py): `data/crud.py`
- [Video model](https://github.com/totallyle1gitaccount/media_service/blob/main/data/models.py): `data/models.py`
- [DB sessions](https://github.com/totallyle1gitaccount/media_service/blob/main/data/core.py): `data/core.py`
- **PostgreSQL**

### Media Integrations

- **FFmpeg / ffprobe**
- **libmagic**
- **Local filesystem**

### Other components

- **API client**

## Connections

- API client → FastAPI app: HTTP requests
- FastAPI app → Video routes: mounts routes
- Video routes → Service dependencies: resolves dependencies
- Video routes → Upload service: upload delegates
- Video routes → Video CRUD: CRUD calls
- Video routes → DB sessions: gets session
- Video routes → Video schemas: validates responses
- Video routes → API schemas: deletion response
- Service dependencies → Upload service: constructs
- Service dependencies → Video validator: injects
- Service dependencies → Probe and normalize: injects
- Service dependencies → File saver: injects
- Service dependencies → Video CRUD: injects
- Upload service → Path generator: generates paths
- Upload service → Video validator: validates upload
- Upload service → Probe and normalize: probes and normalizes
- Upload service → Video CRUD: creates record
- Video validator → libmagic: checks MIME
- Probe and normalize → FFmpeg / ffprobe: runs media tools
- Video CRUD → Video model: queries and writes
- Video CRUD → PostgreSQL: database operations
- DB sessions → PostgreSQL: opens sessions
- Video routes → Local filesystem: deletes video file