# confignomad/study-scribe architecture

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

- Interactive diagram: https://gitdiagram.com/confignomad/study-scribe
- Repository: https://github.com/confignomad/study-scribe

## Overview

StudyScribe is a desktop tool for turning YouTube video or playlist captions into study materials. The intended workflow is to validate or enumerate videos, download caption tracks, format transcripts, and write Markdown or other outputs. The README describes some capabilities as roadmap work, while the indexed service modules and sampled excerpts show additional implementations; the graph represents those modules without assuming every stage is wired into the GUI. Some GUI and service source is unsampled, so unsupported call relationships are omitted.

Main entry points: [`main.py`](https://github.com/confignomad/study-scribe/blob/main/main.py) (Application entry), [`app/gui/main_window.py`](https://github.com/confignomad/study-scribe/blob/main/app/gui/main_window.py) (Main window), [`app/services/markdown_export.py`](https://github.com/confignomad/study-scribe/blob/main/app/services/markdown_export.py) (Markdown generation), [`app/services/exporter.py`](https://github.com/confignomad/study-scribe/blob/main/app/services/exporter.py) (Document export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_entry["Application entry<br/>[main.py]"]
  node_gui["Main window<br/>[main_window.py]"]
  node_settings["App settings<br/>[settings.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

subgraph group_discovery["Video discovery"]
  node_youtube["URL validation<br/>[youtube.py]"]
  node_playlist["Playlist enumeration<br/>[playlist.py]"]
end

subgraph group_transcripts["Caption and transcript processing"]
  node_captions["Caption download<br/>[captions.py]"]
  node_raw[("Raw caption files")]
  node_format["Transcript formatting"]
end

subgraph group_outputs["Study outputs"]
  node_markdown["Markdown generation<br/>[markdown_export.py]"]
  node_exporter["Document export<br/>[exporter.py]"]
  node_studyguide["Study-guide prompts<br/>[study_guide.py]"]
  node_files[("Generated study files")]
end

node_user(("User"))
node_yt(("YouTube"))

node_user -->|"launches"| node_entry
node_entry -->|"launches"| node_gui
node_gui -->|"validates URL"| node_youtube
node_gui -.->|"enumerates playlist"| node_playlist
node_gui -->|"downloads captions"| node_captions
node_youtube -->|"checks availability"| node_yt
node_playlist -->|"fetches metadata"| node_yt
node_captions -->|"fetches tracks"| node_yt
node_captions -->|"writes captions"| node_raw
node_markdown -->|"reads captions"| node_raw
node_exporter -->|"reads captions"| node_raw
node_studyguide -->|"reads captions"| node_raw
node_markdown -->|"formats transcript"| node_format
node_exporter -->|"formats transcript"| node_format
node_studyguide -->|"formats transcript"| node_format
node_markdown -->|"writes Markdown"| node_files
node_exporter -->|"writes formats"| node_files
node_studyguide -->|"writes prompts"| node_files
node_entry -->|"loads settings"| node_settings
node_entry -->|"configures logging"| node_logger

click node_entry "https://github.com/confignomad/study-scribe/blob/main/main.py"
click node_gui "https://github.com/confignomad/study-scribe/blob/main/app/gui/main_window.py"
click node_settings "https://github.com/confignomad/study-scribe/blob/main/app/config/settings.py"
click node_logger "https://github.com/confignomad/study-scribe/blob/main/app/utils/logger.py"
click node_youtube "https://github.com/confignomad/study-scribe/blob/main/app/services/youtube.py"
click node_playlist "https://github.com/confignomad/study-scribe/blob/main/app/services/playlist.py"
click node_captions "https://github.com/confignomad/study-scribe/blob/main/app/services/captions.py"
click node_format "https://github.com/confignomad/study-scribe/blob/main/app/services/transcript_format.py"
click node_markdown "https://github.com/confignomad/study-scribe/blob/main/app/services/markdown_export.py"
click node_exporter "https://github.com/confignomad/study-scribe/blob/main/app/services/exporter.py"
click node_studyguide "https://github.com/confignomad/study-scribe/blob/main/app/services/study_guide.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_entry,node_gui,node_settings,node_logger,node_user toneBlue
class node_youtube,node_playlist toneAmber
class node_captions,node_raw,node_format toneMint
class node_markdown,node_exporter,node_studyguide,node_files toneRose
class node_yt toneIndigo
```

## Components

### Desktop application

- [Application entry](https://github.com/confignomad/study-scribe/blob/main/main.py): `main.py`
- [Main window](https://github.com/confignomad/study-scribe/blob/main/app/gui/main_window.py): `app/gui/main_window.py`
- [App settings](https://github.com/confignomad/study-scribe/blob/main/app/config/settings.py): `app/config/settings.py`
- [Logging](https://github.com/confignomad/study-scribe/blob/main/app/utils/logger.py): `app/utils/logger.py`

### Video discovery

- [URL validation](https://github.com/confignomad/study-scribe/blob/main/app/services/youtube.py): `app/services/youtube.py`
- [Playlist enumeration](https://github.com/confignomad/study-scribe/blob/main/app/services/playlist.py): `app/services/playlist.py`

### Caption and transcript processing

- [Caption download](https://github.com/confignomad/study-scribe/blob/main/app/services/captions.py): `app/services/captions.py`
- **Raw caption files**
- [Transcript formatting](https://github.com/confignomad/study-scribe/blob/main/app/services/transcript_format.py): `app/services/transcript_format.py`

### Study outputs

- [Markdown generation](https://github.com/confignomad/study-scribe/blob/main/app/services/markdown_export.py): `app/services/markdown_export.py`
- [Document export](https://github.com/confignomad/study-scribe/blob/main/app/services/exporter.py): `app/services/exporter.py`
- [Study-guide prompts](https://github.com/confignomad/study-scribe/blob/main/app/services/study_guide.py): `app/services/study_guide.py`
- **Generated study files**

### Other components

- **User**
- **YouTube**

## Connections

- User → Application entry: launches (evidence: `README.md`)
- Application entry → Main window: launches (evidence: `main.py`)
- Main window → URL validation: validates URL (evidence: `README.md`)
- Main window → Playlist enumeration: enumerates playlist (evidence: `app/gui/main_window.py`)
- Main window → Caption download: downloads captions (evidence: `app/gui/main_window.py`)
- URL validation → YouTube: checks availability (evidence: `app/services/youtube.py`)
- Playlist enumeration → YouTube: fetches metadata (evidence: `app/services/playlist.py`)
- Caption download → YouTube: fetches tracks (evidence: `app/services/captions.py`)
- Caption download → Raw caption files: writes captions (evidence: `app/services/captions.py`)
- Markdown generation → Raw caption files: reads captions (evidence: `app/services/markdown_export.py`)
- Document export → Raw caption files: reads captions (evidence: `app/services/exporter.py`)
- Study-guide prompts → Raw caption files: reads captions (evidence: `app/services/study_guide.py`)
- Markdown generation → Transcript formatting: formats transcript (evidence: `app/services/markdown_export.py`)
- Document export → Transcript formatting: formats transcript (evidence: `app/services/exporter.py`)
- Study-guide prompts → Transcript formatting: formats transcript (evidence: `app/services/study_guide.py`)
- Markdown generation → Generated study files: writes Markdown (evidence: `app/services/markdown_export.py`)
- Document export → Generated study files: writes formats (evidence: `app/services/exporter.py`)
- Study-guide prompts → Generated study files: writes prompts (evidence: `app/services/study_guide.py`)
- Application entry → App settings: loads settings (evidence: `main.py`)
- Application entry → Logging: configures logging (evidence: `main.py`)
