# jo-nike/clipforge architecture

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

- Interactive diagram: https://gitdiagram.com/jo-nike/clipforge
- Repository: https://github.com/jo-nike/clipforge

## Overview

ClipForge is a Plex-backed web application for monitoring playback sessions, previewing frames, creating and editing video clips, and managing stored media. The main flow runs from the browser through FastAPI routes into Plex lookup and clip processing, then persists clip records and serves protected files. Authentication, health/metrics, and bulk management are supporting branches. Relationships are limited to README workflows and the supplied source excerpts or index; unsampled implementations are not assumed to have specific call paths.

Main entry points: [`backend/services/clip_service.py`](https://github.com/jo-nike/clipforge/blob/master/backend/services/clip_service.py) (Clip processing), [`backend/services/plex_service.py`](https://github.com/jo-nike/clipforge/blob/master/backend/services/plex_service.py) (Plex integration), [`backend/main.py`](https://github.com/jo-nike/clipforge/blob/master/backend/main.py) (Application server), [`backend/api/v1/auth.py`](https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/auth.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_frontend["Clip interface<br/>[app.js]"]
  node_login["Login interface<br/>[auth.js]"]
end

subgraph group_api["API and access"]
  node_server["Application server<br/>[main.py]"]
  node_auth_api["Authentication routes<br/>[auth.py]"]
  node_clip_api["Clip routes<br/>[clips.py]"]
  node_session_api["Session routes<br/>[sessions.py]"]
  node_storage_api["Storage routes<br/>[storage.py]"]
  node_dependencies["Request dependencies<br/>[dependencies.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
end

subgraph group_media["Media workflow"]
  node_plex["Plex integration<br/>[plex_service.py]"]
  node_clip_service["Clip processing<br/>[clip_service.py]"]
  node_schemas["Domain schemas<br/>[schemas.py]"]
end

subgraph group_data["Persistence and storage"]
  node_secure_storage["Secure file access"]
  node_database[("Database<br/>[database.py]")]
  node_repositories["Data repositories<br/>[repositories.py]"]
end

subgraph group_ops["Platform services"]
  node_security["Security utilities<br/>[security.py]"]
  node_resilience["Resilience controls<br/>[resilience.py]"]
  node_health["Health service<br/>[health_service.py]"]
  node_metrics["Metrics endpoint"]
  node_audit["Audit logging<br/>[audit.py]"]
end

node_user(("User"))
node_plex_server["Plex server"]
node_ffmpeg["FFmpeg"]

node_user -->|"uses"| node_frontend
node_user -->|"signs in"| node_login
node_frontend -.->|"requests"| node_server
node_login -.->|"authenticates"| node_server
node_server -->|"registers routes"| node_auth_api
node_server -->|"registers routes"| node_clip_api
node_server -->|"registers routes"| node_session_api
node_server -->|"registers routes"| node_storage_api
node_auth_api -->|"authenticates with"| node_auth_service
node_auth_api -->|"validates Plex"| node_plex
node_auth_api -->|"accesses users"| node_repositories
node_clip_api -->|"requests processing"| node_clip_service
node_clip_api -->|"gets media details"| node_plex
node_clip_api -->|"manages clip records"| node_repositories
node_session_api -->|"fetches sessions"| node_plex
node_session_api -->|"requests snapshots"| node_clip_service
node_storage_api -->|"serves protected files"| node_secure_storage
node_storage_api -->|"reads media records"| node_repositories
node_dependencies -->|"provides service"| node_clip_service
node_dependencies -->|"provides service"| node_plex
node_dependencies -->|"provides service"| node_secure_storage
node_plex -->|"queries sessions"| node_plex_server
node_clip_service -->|"processes video"| node_ffmpeg
node_clip_service -->|"persists clips"| node_repositories
node_clip_service -->|"uses media service"| node_plex
node_repositories -->|"reads and writes"| node_database
node_secure_storage -->|"queries media records"| node_database
node_auth_service -->|"validates credentials"| node_plex
node_security -->|"validates input"| node_schemas
node_health -->|"checks database"| node_database
node_metrics -->|"gets metrics"| node_dependencies
node_metrics -->|"reads summaries"| node_health
node_auth_api -->|"records events"| node_audit
node_clip_api -->|"records events"| node_audit
node_clip_service -->|"uses safeguards"| node_resilience

click node_frontend "https://github.com/jo-nike/clipforge/blob/master/frontend/static/js/app.js"
click node_login "https://github.com/jo-nike/clipforge/blob/master/frontend/static/js/auth.js"
click node_server "https://github.com/jo-nike/clipforge/blob/master/backend/main.py"
click node_auth_api "https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/auth.py"
click node_clip_api "https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/clips.py"
click node_session_api "https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/sessions.py"
click node_storage_api "https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/storage.py"
click node_dependencies "https://github.com/jo-nike/clipforge/blob/master/backend/api/dependencies.py"
click node_auth_service "https://github.com/jo-nike/clipforge/blob/master/backend/services/auth_service.py"
click node_plex "https://github.com/jo-nike/clipforge/blob/master/backend/services/plex_service.py"
click node_clip_service "https://github.com/jo-nike/clipforge/blob/master/backend/services/clip_service.py"
click node_schemas "https://github.com/jo-nike/clipforge/blob/master/backend/domain/schemas.py"
click node_secure_storage "https://github.com/jo-nike/clipforge/blob/master/backend/services/secure_storage_service.py"
click node_database "https://github.com/jo-nike/clipforge/blob/master/backend/infrastructure/database.py"
click node_repositories "https://github.com/jo-nike/clipforge/blob/master/backend/infrastructure/repositories.py"
click node_security "https://github.com/jo-nike/clipforge/blob/master/backend/core/security.py"
click node_resilience "https://github.com/jo-nike/clipforge/blob/master/backend/core/resilience.py"
click node_health "https://github.com/jo-nike/clipforge/blob/master/backend/services/health_service.py"
click node_metrics "https://github.com/jo-nike/clipforge/blob/master/backend/api/metrics_endpoint.py"
click node_audit "https://github.com/jo-nike/clipforge/blob/master/backend/core/audit.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_frontend,node_login,node_user toneBlue
class node_server,node_auth_api,node_clip_api,node_session_api,node_storage_api,node_dependencies,node_auth_service toneAmber
class node_plex,node_clip_service,node_schemas,node_plex_server toneMint
class node_secure_storage,node_database,node_repositories toneRose
class node_security,node_resilience,node_health,node_metrics,node_audit,node_ffmpeg toneIndigo
```

## Components

### Web interface

- [Clip interface](https://github.com/jo-nike/clipforge/blob/master/frontend/static/js/app.js): `frontend/static/js/app.js`
- [Login interface](https://github.com/jo-nike/clipforge/blob/master/frontend/static/js/auth.js): `frontend/static/js/auth.js`

### API and access

- [Application server](https://github.com/jo-nike/clipforge/blob/master/backend/main.py): `backend/main.py`
- [Authentication routes](https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/auth.py): `backend/api/v1/auth.py`
- [Clip routes](https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/clips.py): `backend/api/v1/clips.py`
- [Session routes](https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/sessions.py): `backend/api/v1/sessions.py`
- [Storage routes](https://github.com/jo-nike/clipforge/blob/master/backend/api/v1/storage.py): `backend/api/v1/storage.py`
- [Request dependencies](https://github.com/jo-nike/clipforge/blob/master/backend/api/dependencies.py): `backend/api/dependencies.py`
- [Authentication service](https://github.com/jo-nike/clipforge/blob/master/backend/services/auth_service.py): `backend/services/auth_service.py`

### Media workflow

- [Plex integration](https://github.com/jo-nike/clipforge/blob/master/backend/services/plex_service.py): `backend/services/plex_service.py`
- [Clip processing](https://github.com/jo-nike/clipforge/blob/master/backend/services/clip_service.py): `backend/services/clip_service.py`
- [Domain schemas](https://github.com/jo-nike/clipforge/blob/master/backend/domain/schemas.py): `backend/domain/schemas.py`

### Persistence and storage

- [Secure file access](https://github.com/jo-nike/clipforge/blob/master/backend/services/secure_storage_service.py): `backend/services/secure_storage_service.py`
- [Database](https://github.com/jo-nike/clipforge/blob/master/backend/infrastructure/database.py): `backend/infrastructure/database.py`
- [Data repositories](https://github.com/jo-nike/clipforge/blob/master/backend/infrastructure/repositories.py): `backend/infrastructure/repositories.py`

### Platform services

- [Security utilities](https://github.com/jo-nike/clipforge/blob/master/backend/core/security.py): `backend/core/security.py`
- [Resilience controls](https://github.com/jo-nike/clipforge/blob/master/backend/core/resilience.py): `backend/core/resilience.py`
- [Health service](https://github.com/jo-nike/clipforge/blob/master/backend/services/health_service.py): `backend/services/health_service.py`
- [Metrics endpoint](https://github.com/jo-nike/clipforge/blob/master/backend/api/metrics_endpoint.py): `backend/api/metrics_endpoint.py`
- [Audit logging](https://github.com/jo-nike/clipforge/blob/master/backend/core/audit.py): `backend/core/audit.py`

### Other components

- **User**
- **Plex server**
- **FFmpeg**

## Connections

- User → Clip interface: uses (evidence: `README.md`)
- User → Login interface: signs in (evidence: `README.md`)
- Clip interface → Application server: requests (evidence: `README.md`)
- Login interface → Application server: authenticates (evidence: `README.md`)
- Application server → Authentication routes: registers routes (evidence: `backend/main.py`)
- Application server → Clip routes: registers routes (evidence: `backend/main.py`)
- Application server → Session routes: registers routes (evidence: `backend/main.py`)
- Application server → Storage routes: registers routes (evidence: `backend/main.py`)
- Authentication routes → Authentication service: authenticates with (evidence: `backend/api/v1/auth.py`)
- Authentication routes → Plex integration: validates Plex (evidence: `backend/api/v1/auth.py`)
- Authentication routes → Data repositories: accesses users (evidence: `backend/api/v1/auth.py`)
- Clip routes → Clip processing: requests processing (evidence: `backend/api/v1/clips.py`)
- Clip routes → Plex integration: gets media details (evidence: `backend/api/v1/clips.py`)
- Clip routes → Data repositories: manages clip records (evidence: `backend/api/v1/clips.py`)
- Session routes → Plex integration: fetches sessions (evidence: `backend/api/v1/sessions.py`)
- Session routes → Clip processing: requests snapshots (evidence: `backend/api/v1/sessions.py`)
- Storage routes → Secure file access: serves protected files (evidence: `backend/api/v1/storage.py`)
- Storage routes → Data repositories: reads media records (evidence: `backend/api/v1/storage.py`)
- Request dependencies → Clip processing: provides service (evidence: `backend/api/dependencies.py`)
- Request dependencies → Plex integration: provides service (evidence: `backend/api/dependencies.py`)
- Request dependencies → Secure file access: provides service (evidence: `backend/api/dependencies.py`)
- Plex integration → Plex server: queries sessions (evidence: `backend/services/plex_service.py`)
- Clip processing → FFmpeg: processes video (evidence: `backend/services/clip_service.py`)
- Clip processing → Data repositories: persists clips (evidence: `backend/services/clip_service.py`)
- Clip processing → Plex integration: uses media service (evidence: `backend/services/clip_service.py`)
- Data repositories → Database: reads and writes (evidence: `backend/infrastructure/repositories.py`)
- Secure file access → Database: queries media records (evidence: `backend/services/secure_storage_service.py`)
- Authentication service → Plex integration: validates credentials (evidence: `backend/services/auth_service.py`)
- Security utilities → Domain schemas: validates input (evidence: `backend/domain/schemas.py`)
- Health service → Database: checks database (evidence: `backend/services/health_service.py`)
- Metrics endpoint → Request dependencies: gets metrics (evidence: `backend/api/metrics_endpoint.py`)
- Metrics endpoint → Health service: reads summaries (evidence: `backend/api/dependencies.py`)
- Authentication routes → Audit logging: records events (evidence: `backend/api/v1/auth.py`)
- Clip routes → Audit logging: records events (evidence: `backend/api/v1/clips.py`)
- Clip processing → Resilience controls: uses safeguards (evidence: `backend/services/clip_service.py`)