# codewithutkarsh12/peakcut-x architecture

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

- Interactive diagram: https://gitdiagram.com/codewithutkarsh12/peakcut-x
- Repository: https://github.com/codewithutkarsh12/peakcut-x

## Overview

PeakCut is a self-hosted service for turning uploaded or linked videos—and live streams—into captioned vertical clips, with optional social posting. The main workflow starts in the dashboard and server, then processes a video through transcription, clip selection, and rendering; live sessions add rolling recording and highlight detection. Separate branches cover creator workspaces, accounts, posting, and administration. Internal edges use the SOURCE INDEX references and excerpts; broader product-flow edges are supported by the README, so unsampled implementation details are not assumed.

Main entry points: [`studio/jobs.py`](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/jobs.py) (Video jobs), [`studio/server.py`](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/server.py) (HTTP server), [`studio/live.py`](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/live.py) (Live sessions), [`studio/brain.py`](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/brain.py) (Clip selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Dashboard and access"]
  node_dashboard["Web dashboard<br/>[index.html]"]
  node_server["HTTP server<br/>[server.py]"]
  node_auth["Sign-in and sessions<br/>[auth.py]"]
  node_accounts["User accounts<br/>[accounts.py]"]
end

subgraph group_clips["Video clipping"]
  node_jobs["Video jobs<br/>[jobs.py]"]
  node_media["Video ingest<br/>[media.py]"]
  node_transcribe["Speech transcription<br/>[transcribe.py]"]
  node_brain["Clip selection<br/>[brain.py]"]
  node_ai["AI providers<br/>[ai.py]"]
  node_render["Clip rendering<br/>[render.py]"]
end

subgraph group_live["Live clipping"]
  node_live["Live sessions<br/>[live.py]"]
end

subgraph group_workspaces["Creators and posting"]
  node_creators["Creator workspaces<br/>[creators.py]"]
  node_profiles["Stream profiles<br/>[profiles.py]"]
  node_posting["Social posting<br/>[posting.py]"]
end

subgraph group_platform["Platform services"]
  node_storage[("Data storage<br/>[storage.py]")]
  node_db[("Account and usage database<br/>[db.py]")]
  node_ctx["User context<br/>[ctx.py]"]
  node_load["Load management<br/>[load.py]"]
  node_usage["AI usage tracking<br/>[usage.py]"]
  node_updates["Update notices<br/>[updates.py]"]
end

node_user(("User"))
node_social(("Social platforms"))
node_ai_service(("AI service"))
node_video_source(("Video or stream source"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"sends requests"| node_server
node_server -->|"handles sign-in"| node_auth
node_server -->|"routes clip jobs"| node_jobs
node_server -->|"routes live sessions"| node_live
node_server -->|"routes posting"| node_posting
node_server -->|"routes workspaces"| node_creators
node_jobs -->|"gets video"| node_media
node_jobs -->|"transcribes audio"| node_transcribe
node_jobs -->|"selects moments"| node_brain
node_brain -->|"requests analysis"| node_ai
node_ai -->|"calls provider"| node_ai_service
node_jobs -->|"renders clips"| node_render
node_media -->|"downloads or probes"| node_video_source
node_live -->|"records stream"| node_video_source
node_live -->|"transcribes live audio"| node_transcribe
node_live -->|"selects highlights"| node_brain
node_live -->|"creates clips"| node_jobs
node_live -->|"uses workspace settings"| node_creators
node_creators -->|"uses profiles"| node_profiles
node_posting -->|"publishes clips"| node_social
node_posting -->|"uses connected accounts"| node_accounts
node_jobs -->|"stores job data"| node_storage
node_creators -->|"stores workspace data"| node_storage
node_auth -->|"stores sessions"| node_db
node_accounts -->|"scopes user data"| node_ctx
node_jobs -->|"checks capacity"| node_load
node_brain -->|"records AI usage"| node_usage
node_usage -->|"writes usage records"| node_db
node_server -->|"shows notices"| node_updates

click node_dashboard "https://github.com/codewithutkarsh12/peakcut-x/blob/main/web/index.html"
click node_server "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/server.py"
click node_auth "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/auth.py"
click node_accounts "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/accounts.py"
click node_jobs "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/jobs.py"
click node_media "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/media.py"
click node_transcribe "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/transcribe.py"
click node_brain "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/brain.py"
click node_ai "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/ai.py"
click node_render "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/render.py"
click node_live "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/live.py"
click node_creators "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/creators.py"
click node_profiles "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/profiles.py"
click node_posting "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/posting.py"
click node_storage "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/storage.py"
click node_db "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/db.py"
click node_ctx "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/ctx.py"
click node_load "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/load.py"
click node_usage "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/usage.py"
click node_updates "https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/updates.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_dashboard,node_server,node_auth,node_accounts,node_user toneBlue
class node_jobs,node_media,node_transcribe,node_brain,node_ai,node_render toneAmber
class node_live toneMint
class node_creators,node_profiles,node_posting toneRose
class node_storage,node_db,node_ctx,node_load,node_usage,node_updates,node_social,node_ai_service,node_video_source toneIndigo
```

## Components

### Dashboard and access

- [Web dashboard](https://github.com/codewithutkarsh12/peakcut-x/blob/main/web/index.html): `web/index.html`
- [HTTP server](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/server.py): `studio/server.py`
- [Sign-in and sessions](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/auth.py): `studio/auth.py`
- [User accounts](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/accounts.py): `studio/accounts.py`

### Video clipping

- [Video jobs](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/jobs.py): `studio/jobs.py`
- [Video ingest](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/media.py): `studio/media.py`
- [Speech transcription](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/transcribe.py): `studio/transcribe.py`
- [Clip selection](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/brain.py): `studio/brain.py`
- [AI providers](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/ai.py): `studio/ai.py`
- [Clip rendering](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/render.py): `studio/render.py`

### Live clipping

- [Live sessions](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/live.py): `studio/live.py`

### Creators and posting

- [Creator workspaces](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/creators.py): `studio/creators.py`
- [Stream profiles](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/profiles.py): `studio/profiles.py`
- [Social posting](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/posting.py): `studio/posting.py`

### Platform services

- [Data storage](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/storage.py): `studio/storage.py`
- [Account and usage database](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/db.py): `studio/db.py`
- [User context](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/ctx.py): `studio/ctx.py`
- [Load management](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/load.py): `studio/load.py`
- [AI usage tracking](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/usage.py): `studio/usage.py`
- [Update notices](https://github.com/codewithutkarsh12/peakcut-x/blob/main/studio/updates.py): `studio/updates.py`

### Other components

- **User**
- **Social platforms**
- **AI service**
- **Video or stream source**

## Connections

- User → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → HTTP server: sends requests (evidence: `studio/server.py`)
- HTTP server → Sign-in and sessions: handles sign-in (evidence: `studio/server.py`)
- HTTP server → Video jobs: routes clip jobs (evidence: `studio/server.py`)
- HTTP server → Live sessions: routes live sessions (evidence: `studio/server.py`)
- HTTP server → Social posting: routes posting (evidence: `studio/server.py`)
- HTTP server → Creator workspaces: routes workspaces (evidence: `studio/server.py`)
- Video jobs → Video ingest: gets video (evidence: `studio/jobs.py`)
- Video jobs → Speech transcription: transcribes audio (evidence: `studio/jobs.py`)
- Video jobs → Clip selection: selects moments (evidence: `studio/jobs.py`)
- Clip selection → AI providers: requests analysis (evidence: `studio/brain.py`)
- AI providers → AI service: calls provider (evidence: `README.md`)
- Video jobs → Clip rendering: renders clips (evidence: `studio/jobs.py`)
- Video ingest → Video or stream source: downloads or probes (evidence: `README.md`)
- Live sessions → Video or stream source: records stream (evidence: `README.md`)
- Live sessions → Speech transcription: transcribes live audio (evidence: `studio/live.py`)
- Live sessions → Clip selection: selects highlights (evidence: `README.md`)
- Live sessions → Video jobs: creates clips (evidence: `studio/live.py`)
- Live sessions → Creator workspaces: uses workspace settings (evidence: `studio/live.py`)
- Creator workspaces → Stream profiles: uses profiles (evidence: `studio/profiles.py`)
- Social posting → Social platforms: publishes clips (evidence: `README.md`)
- Social posting → User accounts: uses connected accounts (evidence: `studio/posting.py`)
- Video jobs → Data storage: stores job data (evidence: `README.md`)
- Creator workspaces → Data storage: stores workspace data (evidence: `studio/creators.py`)
- Sign-in and sessions → Account and usage database: stores sessions (evidence: `studio/auth.py`)
- User accounts → User context: scopes user data (evidence: `studio/accounts.py`)
- Video jobs → Load management: checks capacity (evidence: `studio/jobs.py`)
- Clip selection → AI usage tracking: records AI usage (evidence: `studio/brain.py`)
- AI usage tracking → Account and usage database: writes usage records (evidence: `studio/usage.py`)
- HTTP server → Update notices: shows notices (evidence: `studio/server.py`)
