# leekichang/kbo_video_collection architecture

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

- Interactive diagram: https://gitdiagram.com/leekichang/kbo_video_collection
- Repository: https://github.com/leekichang/kbo_video_collection

## Overview

1. **What this repo is**
   - `kbo_video_collection` is a Python-based downloader and cataloging tool for YouTube KBO playlists.
   - Its core job is to pull videos locally, preserve the accompanying `*.info.json` metadata, and keep enough bookkeeping to avoid re-downloading the same video.

2. **Entry points and runtime shape**
   - The project is packaged as a Python application with a console command (`kbo-videos`) and a module entrypoint in `src/kbo_video_collection/__main__.py`.
   - `cli.py` is the user-facing control layer: it exposes commands like listing configured playlists and running downloads with options such as dry-run and cookie/auth overrides.

3. **Configuration boundary**
   - `playlists.toml` is the primary configuration source.
   - `config.py` is the boundary that reads playlist definitions and YouTube authentication settings, turning TOML into structured application state.
   - The config file drives which playlists are active, where they are stored, and what metadata tags or collection labels are attached.

4. **Core data model**
   - `models.py` likely defines the repository’s internal objects for playlists, manifests, and download records.
   - These models are the glue between configuration, downloader behavior, and the generated output files under `data/`.

5. **Download subsystem**
   - `downloader.py` is the main integration layer around `yt-dlp`.
   - It is responsible for fetching videos, writing the media files, and saving the source metadata JSON next to each video.
   - This is also where format merging and postprocessing depend on `ffmpeg`, which is called out in the README as an external requirement.

6. **External system boundary**
   - The only major external service is YouTube, accessed indirectly through `yt-dlp`.
   - Authentication is optional but supported through browser cookies or a `cookies.txt` file when YouTube requires login.
   - `ffmpeg` is a local system dependency, not a Python dependency, but it materially affects whether merged video downloads succeed.

7. **Storage layout and persistence**
   - The repository persists three kinds of local state:
     - `data/raw/<playlist-name>/<year>/...` for the actual media files and their `*.info.json` companions
     - `data/manifests/<playlist-name>.json` for playlist-level collection metadata
     - `data/.archives/<playlist-name>.txt` for the set of YouTube video IDs already collected
   - This layout separates raw artifacts from indexing/state files, which is important for understanding the pipeline.

8. **Idempotency and replay behavior**
   - The downloader is designed to be rerun safely.
   - It uses a `yt-dlp` archive file to skip already-downloaded video IDs.
   - If the archive file is missing, it can reconstruct that state by scanning existing `data/raw` outputs and matching each media file with its `*.info.json`.

9. **Repository-specific artifact boundary**
   - The `src/kbo_video_collection/NA/…info.json` file in the tree looks like a captured YouTube metadata artifact, not source code.
   - It shows that metadata is treated as a first-class output and may be used later for event-level classification or other downstream analysis.

10. **Operational flow**
   - A typical run is: load `playlists.toml` → select enabled playlists or a specific playlist → resolve auth options → call `yt-dlp` for each playlist item → write media plus `info.json` → update archive/manifests.
   - The `dry-run` mode lets the CLI validate that flow without writing downloads, which is useful for checking configuration and playlist reachability.

11. **Dependency and environment management**
   - `pyproject.toml` handles packaging/installability, while `environment.yml` supports a Conda-based setup.
   - The README explicitly recommends `ffmpeg` availability, so the repo straddles both Python packaging and system-level media tooling.

12. **Architectural takeaway**
   - This is not a general-purpose media app; it is a narrow ingestion-and-metadata preservation pipeline.
   - The key diagram boundary is between: configuration/CLI on one side, YouTube/yt-dlp/ffmpeg on the other, and a local filesystem-based persistence layer in the middle that preserves both raw video and replay state.

Main entry points: [`src/kbo_video_collection/downloader.py`](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/downloader.py) (Downloader), [`src/kbo_video_collection/cli.py`](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/cli.py) (CLI), [`src/kbo_video_collection/config.py`](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/config.py) (Config loader), [`README.md`](https://github.com/leekichang/kbo_video_collection/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application"]
  node_cli["CLI<br/>command layer<br/>[cli.py]"]
  node_entrypoint["Module entry<br/>python entrypoint<br/>[__main__.py]"]
  node_packaging["Packaging<br/>project config<br/>[pyproject.toml]"]
  node_conda["Env spec<br/>runtime setup<br/>[environment.yml]"]
  node_readme["README<br/>docs<br/>[README.md]"]
end

subgraph group_configuration["Configuration"]
  node_config["Config loader<br/>config boundary<br/>[config.py]"]
  node_playlists["Playlists<br/>toml source<br/>[playlists.toml]"]
  node_models["Models<br/>domain model<br/>[models.py]"]
end

subgraph group_pipeline["Download pipeline"]
  node_downloader["Downloader<br/>orchestrator<br/>[downloader.py]"]
end

subgraph group_persistence["Local state"]
  node_rawdata[("Raw video<br/>media output")]
  node_manifests[("Manifests<br/>index store")]
  node_archive["Archive<br/>replay state"]
  node_infometadata["Info JSON<br/>captured artifact"]
end

subgraph group_external["External systems"]
  node_ytdlp["yt-dlp<br/>fetch engine"]
  node_ffmpeg["ffmpeg<br/>media tool"]
  node_youtube(("YouTube<br/>remote source"))
end

node_entrypoint -->|"starts"| node_cli
node_packaging -->|"exposes"| node_cli
node_cli -->|"loads"| node_config
node_cli -->|"runs"| node_downloader
node_config -->|"parses"| node_playlists
node_config -->|"builds"| node_models
node_downloader -->|"uses"| node_models
node_downloader -->|"delegates"| node_ytdlp
node_ytdlp -->|"fetches from"| node_youtube
node_downloader -->|"depends on"| node_ffmpeg
node_downloader -->|"writes"| node_rawdata
node_downloader -->|"writes"| node_infometadata
node_downloader -->|"updates"| node_manifests
node_downloader -->|"updates"| node_archive
node_downloader -->|"scans"| node_rawdata
node_downloader -->|"rebuilds"| node_archive
node_conda -->|"requires"| node_ffmpeg
node_readme -->|"documents"| node_config
node_readme -->|"documents"| node_downloader

click node_cli "https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/cli.py"
click node_entrypoint "https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/__main__.py"
click node_packaging "https://github.com/leekichang/kbo_video_collection/blob/main/pyproject.toml"
click node_conda "https://github.com/leekichang/kbo_video_collection/blob/main/environment.yml"
click node_readme "https://github.com/leekichang/kbo_video_collection/blob/main/README.md"
click node_config "https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/config.py"
click node_playlists "https://github.com/leekichang/kbo_video_collection/blob/main/playlists.toml"
click node_models "https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/models.py"
click node_downloader "https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/downloader.py"
click node_infometadata "https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/NA/⚾ 2024 KBO 리그 [PLQSdHthiYH-8FiPjoGS0YbFtsn_QxzinI].info.json"

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_cli,node_entrypoint,node_packaging,node_conda,node_readme toneBlue
class node_config,node_playlists,node_models toneAmber
class node_downloader toneMint
class node_rawdata,node_manifests,node_archive,node_infometadata toneRose
class node_ytdlp,node_ffmpeg,node_youtube toneIndigo
```

## Components

### Application

User-facing entrypoints and project packaging

- [CLI](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/cli.py): command layer · User-facing commands for listing playlists and running downloads · `src/kbo_video_collection/cli.py`
- [Module entry](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/__main__.py): python entrypoint · Package entrypoint for running the tool as a module · `src/kbo_video_collection/__main__.py`
- [Packaging](https://github.com/leekichang/kbo_video_collection/blob/main/pyproject.toml): project config · Python packaging and console-script definition · `pyproject.toml`
- [Env spec](https://github.com/leekichang/kbo_video_collection/blob/main/environment.yml): runtime setup · Conda environment specification for local development and execution · `environment.yml`
- [README](https://github.com/leekichang/kbo_video_collection/blob/main/README.md): docs · Operational overview and setup guidance · `README.md`

### Configuration

Playlist definitions and runtime settings

- [Config loader](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/config.py): config boundary · Loads playlist definitions and auth settings from TOML · `src/kbo_video_collection/config.py`
- [Playlists](https://github.com/leekichang/kbo_video_collection/blob/main/playlists.toml): toml source · Primary repository configuration for active playlists and storage targets · `playlists.toml`
- [Models](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/models.py): domain model · Internal objects for playlists, manifests, and download records · `src/kbo_video_collection/models.py`

### Download pipeline

Fetch, postprocess, and local persistence flow

- [Downloader](https://github.com/leekichang/kbo_video_collection/blob/main/src/kbo_video_collection/downloader.py): orchestrator · Coordinates playlist downloads and local artifact creation · `src/kbo_video_collection/downloader.py`

### Local state

Repository artifacts and replay bookkeeping

- **Raw video**: media output · Downloaded media files and companion metadata preserved locally
- **Manifests**: index store · Playlist-level collection metadata stored as local JSON
- **Archive**: replay state · Collected video ID ledger used to skip already-downloaded items
- [Info JSON](https://github.com/leekichang/kbo_video_collection/blob/HEAD/src/kbo_video_collection/NA/%E2%9A%BE%202024%20KBO%20%EB%A6%AC%EA%B7%B8%20%5BPLQSdHthiYH-8FiPjoGS0YbFtsn_QxzinI%5D.info.json): captured artifact · Saved YouTube metadata companion file preserved next to each video · `src/kbo_video_collection/NA/⚾ 2024 KBO 리그 [PLQSdHthiYH-8FiPjoGS0YbFtsn_QxzinI].info.json`

### External systems

Third-party and system dependencies

- **yt-dlp**: fetch engine · Third-party download engine used to retrieve videos and metadata
- **ffmpeg**: media tool · System dependency for merging and postprocessing video downloads
- **YouTube**: remote source · Source platform for playlist videos and metadata

## Connections

- Module entry → CLI: starts · Module entrypoint dispatches into the CLI layer
- Packaging → CLI: exposes · Defines the installable console command
- CLI → Config loader: loads · Reads playlist and auth configuration before executing commands
- CLI → Downloader: runs · Invokes the download workflow for selected playlists
- Config loader → Playlists: parses · Turns TOML playlist definitions into structured state
- Config loader → Models: builds · Creates domain objects used throughout the app
- Downloader → Models: uses · Consumes playlist and record models during orchestration
- Downloader → yt-dlp: delegates · Hands off fetch and metadata retrieval to yt-dlp
- yt-dlp → YouTube: fetches from · Downloads videos and metadata from YouTube
- Downloader → ffmpeg: depends on · Relies on ffmpeg for merging and postprocessing
- Downloader → Raw video: writes · Stores downloaded media files and companion metadata locally
- Downloader → Info JSON: writes · Persists source metadata JSON next to each media file
- Downloader → Manifests: updates · Records playlist-level manifest output
- Downloader → Archive: updates · Maintains replay state for already-collected video IDs
- Downloader → Raw video: scans · Can reconstruct archive state by inspecting existing downloads
- Downloader → Archive: rebuilds · Regenerates archive entries when the archive file is missing
- Env spec → ffmpeg: requires · Supports a local runtime that also needs ffmpeg installed
- README → Config loader: documents · Explains configuration, authentication, and usage flow
- README → Downloader: documents · Describes download behavior and operational requirements
