# rockyroad1827/bookstacks-youtube-video-sync architecture

> Architecture diagram of the GitHub repository rockyroad1827/bookstacks-youtube-video-sync, 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/rockyroad1827/bookstacks-youtube-video-sync
- Repository: https://github.com/rockyroad1827/bookstacks-youtube-video-sync

## Overview

This repository syncs YouTube channel videos into a configured BookStack book, organizing playlist videos into chapters and uncategorized videos at the book root. The main script also detects already-synced videos, supports forced deletion and resync, and can run a recycle-bin purge. The README documents OAuth token setup and the purge workflow; excerpts show selected API operations but omit much of the main script, so uncertain internal call wiring is not expanded.

Main entry points: [`Sync Public Videos.py`](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py) (Sync coordinator), [`oauth2 token.py`](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/oauth2%20token.py) (OAuth token helper), [`purge_recycle_bin.sh`](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/purge_recycle_bin.sh) (Recycle-bin purge), [`purge_query.sql`](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/purge_query.sql) (Purge query)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sync["Video Sync"]
  node_sync_main["Sync coordinator"]
  node_discover["Playlist discovery"]
  node_videos["Video details"]
  node_classify["Playlist grouping"]
  node_book_index["Existing page scan"]
  node_chapters["Chapter management"]
  node_pages["Page management"]
end

subgraph group_auth["Authentication"]
  node_oauth["OAuth token helper<br/>[oauth2 token.py]"]
  node_token_file["Token file"]
end

subgraph group_purge["Purge"]
  node_purge_call["Purge invocation"]
  node_purge_shell["Recycle-bin purge"]
  node_purge_sql["Purge query<br/>[purge_query.sql]"]
end

node_operator(("Operator"))
node_youtube["YouTube API"]
node_bookstack["BookStack API"]
node_google_oauth["Google OAuth"]
node_database[("BookStack database")]

node_operator -->|"runs sync"| node_sync_main
node_sync_main -->|"collects playlists"| node_discover
node_discover -->|"requests playlists"| node_youtube
node_sync_main -->|"gets video details"| node_videos
node_videos -->|"requests videos"| node_youtube
node_sync_main -->|"groups videos"| node_classify
node_sync_main -->|"checks duplicates"| node_book_index
node_book_index -->|"reads book pages"| node_bookstack
node_sync_main -->|"syncs playlists"| node_chapters
node_chapters -->|"creates chapters"| node_bookstack
node_sync_main -->|"syncs videos"| node_pages
node_pages -->|"creates pages"| node_bookstack
node_operator -->|"starts login"| node_oauth
node_oauth -->|"authenticates"| node_google_oauth
node_oauth -->|"saves credentials"| node_token_file
node_operator -->|"runs sync"| node_purge_call
node_purge_call -->|"executes script"| node_purge_shell
node_purge_shell -->|"uses query"| node_purge_sql
node_purge_sql -->|"purges records"| node_database

click node_sync_main "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_discover "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_videos "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_classify "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_book_index "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_chapters "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_pages "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_oauth "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/oauth2%20token.py"
click node_purge_call "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py"
click node_purge_shell "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/purge_recycle_bin.sh"
click node_purge_sql "https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/purge_query.sql"

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_sync_main,node_discover,node_videos,node_classify,node_book_index,node_chapters,node_pages toneBlue
class node_oauth,node_token_file,node_database toneAmber
class node_purge_call,node_purge_shell,node_purge_sql,node_youtube,node_bookstack toneMint
class node_operator,node_google_oauth toneIndigo
```

## Components

### Video Sync

- [Sync coordinator](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`
- [Playlist discovery](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`
- [Video details](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`
- [Playlist grouping](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`
- [Existing page scan](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`
- [Chapter management](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`
- [Page management](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`

### Authentication

- [OAuth token helper](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/oauth2%20token.py): `oauth2 token.py`
- **Token file**

### Purge

- [Purge invocation](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/Sync%20Public%20Videos.py): `Sync Public Videos.py`
- [Recycle-bin purge](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/purge_recycle_bin.sh): `purge_recycle_bin.sh`
- [Purge query](https://github.com/rockyroad1827/bookstacks-youtube-video-sync/blob/main/purge_query.sql): `purge_query.sql`

### Other components

- **Operator**
- **YouTube API**
- **BookStack API**
- **Google OAuth**
- **BookStack database**

## Connections

- Operator → Sync coordinator: runs sync
- Sync coordinator → Playlist discovery: collects playlists
- Playlist discovery → YouTube API: requests playlists
- Sync coordinator → Video details: gets video details
- Video details → YouTube API: requests videos
- Sync coordinator → Playlist grouping: groups videos
- Sync coordinator → Existing page scan: checks duplicates
- Existing page scan → BookStack API: reads book pages
- Sync coordinator → Chapter management: syncs playlists
- Chapter management → BookStack API: creates chapters
- Sync coordinator → Page management: syncs videos
- Page management → BookStack API: creates pages
- Operator → OAuth token helper: starts login
- OAuth token helper → Google OAuth: authenticates
- OAuth token helper → Token file: saves credentials
- Operator → Purge invocation: runs sync
- Purge invocation → Recycle-bin purge: executes script
- Recycle-bin purge → Purge query: uses query
- Purge query → BookStack database: purges records