# antony-collika/subgrab architecture

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

- Interactive diagram: https://gitdiagram.com/antony-collika/subgrab
- Repository: https://github.com/antony-collika/subgrab

## Overview

SubGrab is an Android app for discovering YouTube videos and downloading subtitles, with a separate research workspace for searching and examining video metadata. The primary flow is URL, keyword, or playlist discovery; subtitle-track extraction; parsing and normalization; formatting as SRT or TXT; and saving or publishing files. The research branch supports searchable video records, history and detail views, transcripts, comments, and export. The README documents the subtitle pipeline; source excerpts confirm UI, extraction, storage, and research persistence components, but do not expose all orchestration calls.

Main entry points: [`app/src/main/java/com/subgrab/app/service/DownloadWorker.kt`](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/service/DownloadWorker.kt) (Download worker), [`app/src/main/java/com/subgrab/app/ui/ResearchSearchViewModel.kt`](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/ui/ResearchSearchViewModel.kt) (Research view models), [`app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt`](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt) (Subtitle extraction), [`app/src/main/java/com/subgrab/app/data/SubGrabDatabase.kt`](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubGrabDatabase.kt) (Runtime database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App workflow"]
  node_activity["App navigation<br/>[MainActivity.kt]"]
  node_download_ui["Download UI"]
  node_worker["Download worker<br/>[DownloadWorker.kt]"]
end

subgraph group_subtitle["Subtitle pipeline"]
  node_discovery["Video discovery"]
  node_extractor["Subtitle extraction"]
  node_subtitle_download["Subtitle download"]
  node_parser["Cue parsing<br/>[SubtitleParser.kt]"]
  node_normalizer["Cue normalization"]
  node_formatter["SRT/TXT formatting"]
  node_storage["File publishing<br/>[FileStorage.kt]"]
end

subgraph group_research["Research workspace"]
  node_research_ui["Research screens<br/>[ResearchScreens.kt]"]
  node_research_vm["Research view models"]
  node_research_repo["Research queries"]
  node_knowledge_repo["Knowledge records"]
  node_export["Research export<br/>[ResearchExport.kt]"]
end

subgraph group_data["Data and integrations"]
  node_api["YouTube API"]
  node_settings["App settings"]
  node_database[("Runtime database<br/>[SubGrabDatabase.kt]")]
end

node_user(("User"))
node_youtube(("YouTube"))

node_user -->|"uses"| node_activity
node_activity -->|"routes actions"| node_download_ui
node_download_ui -->|"starts download"| node_worker
node_worker -->|"initializes"| node_extractor
node_discovery -->|"fetches videos"| node_youtube
node_extractor -->|"fetches tracks"| node_youtube
node_extractor -->|"provides extractor"| node_subtitle_download
node_subtitle_download -->|"parses cues"| node_parser
node_parser -->|"normalizes cues"| node_normalizer
node_normalizer -->|"formats cues"| node_formatter
node_formatter -->|"writes files"| node_storage
node_user -->|"uses"| node_research_ui
node_research_ui -->|"dispatches actions"| node_research_vm
node_research_vm -->|"queries"| node_research_repo
node_research_vm -->|"loads details"| node_knowledge_repo
node_research_repo -->|"searches records"| node_database
node_knowledge_repo -->|"reads/writes"| node_database
node_research_vm -->|"exports results"| node_export
node_api -.->|"requests metadata"| node_youtube
node_settings -->|"supplies API key"| node_api
node_worker -->|"loads settings"| node_settings
node_worker -->|"logs runtime"| node_database

click node_activity "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/MainActivity.kt"
click node_download_ui "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/ui/DownloadViewModel.kt"
click node_worker "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/service/DownloadWorker.kt"
click node_discovery "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt"
click node_extractor "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt"
click node_subtitle_download "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleDownloader.kt"
click node_parser "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleParser.kt"
click node_normalizer "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleNormalizer.kt"
click node_formatter "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleFormatter.kt"
click node_storage "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/FileStorage.kt"
click node_research_ui "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/ui/ResearchScreens.kt"
click node_research_vm "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/ui/ResearchSearchViewModel.kt"
click node_research_repo "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/repository/ResearchRepository.kt"
click node_knowledge_repo "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/repository/KnowledgeRepository.kt"
click node_export "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/export/ResearchExport.kt"
click node_api "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/YouTubeDataApiClient.kt"
click node_settings "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SettingsRepository.kt"
click node_database "https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubGrabDatabase.kt"

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_activity,node_download_ui,node_worker,node_user toneBlue
class node_discovery,node_extractor,node_subtitle_download,node_parser,node_normalizer,node_formatter,node_storage toneAmber
class node_research_ui,node_research_vm,node_research_repo,node_knowledge_repo,node_export toneMint
class node_api,node_settings,node_database toneRose
class node_youtube toneIndigo
```

## Components

### App workflow

- [App navigation](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/MainActivity.kt): `app/src/main/java/com/subgrab/app/MainActivity.kt`
- [Download UI](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/ui/DownloadViewModel.kt): `app/src/main/java/com/subgrab/app/ui/DownloadViewModel.kt`
- [Download worker](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/service/DownloadWorker.kt): `app/src/main/java/com/subgrab/app/service/DownloadWorker.kt`

### Subtitle pipeline

- [Video discovery](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt): `app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt`
- [Subtitle extraction](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt): `app/src/main/java/com/subgrab/app/data/NewPipeExtractorClient.kt`
- [Subtitle download](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleDownloader.kt): `app/src/main/java/com/subgrab/app/data/SubtitleDownloader.kt`
- [Cue parsing](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleParser.kt): `app/src/main/java/com/subgrab/app/data/SubtitleParser.kt`
- [Cue normalization](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleNormalizer.kt): `app/src/main/java/com/subgrab/app/data/SubtitleNormalizer.kt`
- [SRT/TXT formatting](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubtitleFormatter.kt): `app/src/main/java/com/subgrab/app/data/SubtitleFormatter.kt`
- [File publishing](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/FileStorage.kt): `app/src/main/java/com/subgrab/app/data/FileStorage.kt`

### Research workspace

- [Research screens](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/ui/ResearchScreens.kt): `app/src/main/java/com/subgrab/app/ui/ResearchScreens.kt`
- [Research view models](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/ui/ResearchSearchViewModel.kt): `app/src/main/java/com/subgrab/app/ui/ResearchSearchViewModel.kt`
- [Research queries](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/repository/ResearchRepository.kt): `app/src/main/java/com/subgrab/app/data/repository/ResearchRepository.kt`
- [Knowledge records](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/repository/KnowledgeRepository.kt): `app/src/main/java/com/subgrab/app/data/repository/KnowledgeRepository.kt`
- [Research export](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/export/ResearchExport.kt): `app/src/main/java/com/subgrab/app/data/export/ResearchExport.kt`

### Data and integrations

- [YouTube API](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/YouTubeDataApiClient.kt): `app/src/main/java/com/subgrab/app/data/YouTubeDataApiClient.kt`
- [App settings](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SettingsRepository.kt): `app/src/main/java/com/subgrab/app/data/SettingsRepository.kt`
- [Runtime database](https://github.com/antony-collika/subgrab/blob/first-Draft/app/src/main/java/com/subgrab/app/data/SubGrabDatabase.kt): `app/src/main/java/com/subgrab/app/data/SubGrabDatabase.kt`

### Other components

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

## Connections

- User → App navigation: uses
- App navigation → Download UI: routes actions
- Download UI → Download worker: starts download
- Download worker → Subtitle extraction: initializes
- Video discovery → YouTube: fetches videos
- Subtitle extraction → YouTube: fetches tracks
- Subtitle extraction → Subtitle download: provides extractor
- Subtitle download → Cue parsing: parses cues
- Cue parsing → Cue normalization: normalizes cues
- Cue normalization → SRT/TXT formatting: formats cues
- SRT/TXT formatting → File publishing: writes files
- User → Research screens: uses
- Research screens → Research view models: dispatches actions
- Research view models → Research queries: queries
- Research view models → Knowledge records: loads details
- Research queries → Runtime database: searches records
- Knowledge records → Runtime database: reads/writes
- Research view models → Research export: exports results
- YouTube API → YouTube: requests metadata
- App settings → YouTube API: supplies API key
- Download worker → App settings: loads settings
- Download worker → Runtime database: logs runtime