# mxpv/podsync architecture

> Architecture diagram of the GitHub repository mxpv/podsync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mxpv/podsync
- Repository: https://github.com/mxpv/podsync

## Overview

##### Project Type and Purpose
- Podsync is a backend service (Go-based CLI + HTTP server) that generates podcast RSS feeds from YouTube, Vimeo, SoundCloud, Twitch and serves them via HTTP.
- It has two main roles: feed/updater service (scheduler + media builder + storage) and web service (HTTP server to serve RSS + media).

##### File Structure
- cmd/podsync: entrypoint with configuration loading (config.go) and main.go launching services.
- pkg/builder: modules that, given a feed URL, fetch video lists and build media (youtube, vimeo, soundcloud, twitch).
- pkg/ytdl: wrapper around yt-dlp + temp file handling.
- pkg/db: BadgerDB storage for feed metadata and state.
- pkg/fs: abstraction for file storage (local filesystem or S3).
- pkg/feed: RSS feed generation, OPML export, hooks, filters.
- pkg/model: domain models (Feed, Link, defaults, errors).
- services/update: scheduler (cron), feed updater (matcher/updater).
- services/web: HTTP server exposing RSS and static assets.
- config.toml.example + environment variables define service behavior, API keys, storage, server port.
- docker-compose.yml, Dockerfile, cloud_formation.yml: deployment artifacts for containerized environments and AWS.

##### Key Architectural Patterns
- Modular service layers: “builder” for media retrieval, “feed” for RSS construction, “db” for state, “fs” for storage, “web” for HTTP server, “update” for scheduling.
- Dependency injection via pkg/feed/deps.go for mocking/testing.
- Adapter pattern in pkg/fs to switch storage backends.
- Cron-driven scheduler to periodically update feeds.
- Single-binary deployment via Go, Docker, or AWS CloudFormation.

##### Main Components
A. Client Configuration
- config.toml or environment variables
B. Scheduler (services/update)
- cron expressions trigger Updater
C. Feed Updater
- matcher.go (decide which episodes are new)
- updater.go (invoke builder modules)
D. Builder Modules (pkg/builder + pkg/ytdl)
- fetch metadata via APIs (YouTube, Vimeo, etc.)
- download media via yt-dlp, transcode with ffmpeg (outside Go but invoked)
E. Storage
- Metadata: BadgerDB (pkg/db)
- Media files: local FS or S3 (pkg/fs)
F. Feed Generator (pkg/feed)
- assemble RSS XML, apply filters, hooks, OPML export
G. Web Server (services/web)
- HTTP endpoints: /{feedID}/rss.xml, /{feedID}/{episodeID}.mp3
- Serve static HTML (html/index.html)
H. External Services
- YouTube/Vimeo/SoundCloud/Twitch APIs
- yt-dlp and ffmpeg command-line tools
I. Deployment / Infrastructure
- Docker container, Docker Compose, AWS CloudFormation
- CI/CD workflows (.github/workflows)

##### Relationships and Data Flows
1. At startup, main.go reads configuration → initializes DB, FS, scheduler, web server.
2. Scheduler triggers feed updater per cron → feed updater invokes builder modules.
3. Builder modules call external APIs → download media via yt-dlp → transcode if needed → write media files to FS.
4. Updater writes metadata/state to BadgerDB.
5. Web server handles HTTP requests:
- For RSS: reads metadata from DB + builds RSS via pkg/feed → returns XML.
- For media: serves files from FS.
6. Clients (podcast apps) poll RSS feeds → download episodes.
7. OPML export provided via feed generator for bulk imports.

##### Technologies and Frameworks to Annotate
- Go modules, Go standard library (net/http, database/sql, etc.)
- BadgerDB (embedded key-value store)
- S3 SDK (AWS)
- yt-dlp, ffmpeg (external)
- Cron expressions (robfig/cron or built-in)
- Docker, Docker Compose, AWS CloudFormation
- CI/CD: GitHub Actions, goreleaser

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Configuration"
    ConfigFile["Config (cmd/podsync/config.go)"]:::internal
    ConfigExample["config.toml.example"]:::internal
  end
  click ConfigFile "https://github.com/mxpv/podsync/blob/main/cmd/podsync/config.go"
  click ConfigExample "https://github.com/mxpv/podsync/blob/main/config.toml.example"

  Entry["Entry Point (main.go)"]:::internal
  click Entry "https://github.com/mxpv/podsync/blob/main/cmd/podsync/main.go"

  subgraph "Scheduler & Updater"
    Matcher["Matcher (services/update/matcher.go)"]:::internal
    Updater["Updater (services/update/updater.go)"]:::internal
    CronDoc["Cron Docs (docs/cron.md)"]:::external
  end
  click Matcher "https://github.com/mxpv/podsync/blob/main/services/update/matcher.go"
  click Updater "https://github.com/mxpv/podsync/blob/main/services/update/updater.go"
  click CronDoc "https://github.com/mxpv/podsync/blob/main/docs/cron.md"

  subgraph "Media Builder"
    BuilderCore["Builder Core (pkg/builder/builder.go)"]:::internal
    YT["YouTube Adapter (pkg/builder/youtube.go)"]:::internal
    Vi["Vimeo Adapter (pkg/builder/vimeo.go)"]:::internal
    SC["SoundCloud Adapter (pkg/builder/soundcloud.go)"]:::internal
    Tw["Twitch Adapter (pkg/builder/twitch.go)"]:::internal
    URLMod["URL Parser (pkg/builder/url.go)"]:::internal
  end
  click BuilderCore "https://github.com/mxpv/podsync/blob/main/pkg/builder/builder.go"
  click YT "https://github.com/mxpv/podsync/blob/main/pkg/builder/youtube.go"
  click Vi "https://github.com/mxpv/podsync/blob/main/pkg/builder/vimeo.go"
  click SC "https://github.com/mxpv/podsync/blob/main/pkg/builder/soundcloud.go"
  click Tw "https://github.com/mxpv/podsync/blob/main/pkg/builder/twitch.go"
  click URLMod "https://github.com/mxpv/podsync/blob/main/pkg/builder/url.go"

  subgraph "yt-dlp Wrapper"
    YTDL["yt-dlp Wrapper (pkg/ytdl/ytdl.go)"]:::external
    TempFile["Temp File Handler (pkg/ytdl/temp_file.go)"]:::external
  end
  click YTDL "https://github.com/mxpv/podsync/blob/main/pkg/ytdl/ytdl.go"
  click TempFile "https://github.com/mxpv/podsync/blob/main/pkg/ytdl/temp_file.go"

  subgraph "Storage Backends"
    subgraph "Metadata Storage"
      DBCore["BadgerDB (pkg/db/badger.go)"]:::storage
      DBStorage["DB Storage (pkg/db/storage.go)"]:::storage
      DBConfig["DB Config (pkg/db/config.go)"]:::storage
    end
    subgraph "File Storage"
      LocalFS["Local FS (pkg/fs/local.go)"]:::storage
      S3FS["S3 FS (pkg/fs/s3.go)"]:::storage
      FSCore["FS Abstraction (pkg/fs/storage.go)"]:::storage
    end
  end
  click DBCore "https://github.com/mxpv/podsync/blob/main/pkg/db/badger.go"
  click DBStorage "https://github.com/mxpv/podsync/blob/main/pkg/db/storage.go"
  click DBConfig "https://github.com/mxpv/podsync/blob/main/pkg/db/config.go"
  click LocalFS "https://github.com/mxpv/podsync/blob/main/pkg/fs/local.go"
  click S3FS "https://github.com/mxpv/podsync/blob/main/pkg/fs/s3.go"
  click FSCore "https://github.com/mxpv/podsync/blob/main/pkg/fs/storage.go"

  subgraph "Feed Generation"
    FeedConfig["Feed Config (pkg/feed/config.go)"]:::internal
    Deps["DI Deps (pkg/feed/deps.go)"]:::internal
    Hooks["Hooks (pkg/feed/hooks.go)"]:::internal
    OPML["OPML (pkg/feed/opml.go)"]:::internal
    XML["XML (pkg/feed/xml.go)"]:::internal
    Key["Key Management (pkg/feed/key.go)"]:::internal
  end
  click FeedConfig "https://github.com/mxpv/podsync/blob/main/pkg/feed/config.go"
  click Deps "https://github.com/mxpv/podsync/blob/main/pkg/feed/deps.go"
  click Hooks "https://github.com/mxpv/podsync/blob/main/pkg/feed/hooks.go"
  click OPML "https://github.com/mxpv/podsync/blob/main/pkg/feed/opml.go"
  click XML "https://github.com/mxpv/podsync/blob/main/pkg/feed/xml.go"
  click Key "https://github.com/mxpv/podsync/blob/main/pkg/feed/key.go"

  subgraph "Domain Models"
    MFeed["Feed Model (pkg/model/feed.go)"]:::internal
    MLink["Link Model (pkg/model/link.go)"]:::internal
    MDefaults["Defaults (pkg/model/defaults.go)"]:::internal
    MErrors["Errors (pkg/model/errors.go)"]:::internal
  end
  click MFeed "https://github.com/mxpv/podsync/blob/main/pkg/model/feed.go"
  click MLink "https://github.com/mxpv/podsync/blob/main/pkg/model/link.go"
  click MDefaults "https://github.com/mxpv/podsync/blob/main/pkg/model/defaults.go"
  click MErrors "https://github.com/mxpv/podsync/blob/main/pkg/model/errors.go"

  subgraph "Web Server"
    Server["HTTP Server (services/web/server.go)"]:::internal
    HTML["Static HTML (html/index.html)"]:::internal
  end
  click Server "https://github.com/mxpv/podsync/blob/main/services/web/server.go"
  click HTML "https://github.com/mxpv/podsync/blob/main/html/index.html"

  subgraph "External APIs & Tools"
    YouTubeAPI["YouTube API"]:::external
    VimeoAPI["Vimeo API"]:::external
    SCAPI["SoundCloud API"]:::external
    TwitchAPI["Twitch API"]:::external
    FFmpeg["ffmpeg"]:::external
  end

  subgraph "Deployment & CI/CD"
    DockerfileNode["Dockerfile"]:::infra
    Compose["docker-compose.yml"]:::infra
    CF["cloud_formation.yml"]:::infra
    GHActions["GitHub Workflows"]:::infra
    Goreleaser[".goreleaser.yml"]:::infra
  end
  click DockerfileNode "https://github.com/mxpv/podsync/tree/main/Dockerfile"
  click Compose "https://github.com/mxpv/podsync/blob/main/docker-compose.yml"
  click CF "https://github.com/mxpv/podsync/blob/main/cloud_formation.yml"
  click GHActions "https://github.com/mxpv/podsync/blob/main/.github/workflows/ci.yml"
  click GHActions "https://github.com/mxpv/podsync/blob/main/.github/workflows/nightly.yml"
  click GHActions "https://github.com/mxpv/podsync/blob/main/.github/workflows/release.yml"
  click GHActions "https://github.com/mxpv/podsync/blob/main/.github/workflows/claude.yml"
  click GHActions "https://github.com/mxpv/podsync/blob/main/.github/workflows/dedup.yml"
  click GHActions "https://github.com/mxpv/podsync/blob/main/.github/workflows/triage.yml"
  click Goreleaser "https://github.com/mxpv/podsync/blob/main/.goreleaser.yml"

  %% Connections
  ConfigFile --> Entry
  ConfigExample --> Entry
  Entry --> Matcher
  Entry --> Server
  Matcher -->|trigger| Updater
  Updater -->|invokes| BuilderCore
  BuilderCore --> YT
  BuilderCore --> Vi
  BuilderCore --> SC
  BuilderCore --> Tw
  BuilderCore --> URLMod
  YT --> YouTubeAPI
  Vi --> VimeoAPI
  SC --> SCAPI
  Tw --> TwitchAPI
  BuilderCore --> YTDL
  YTDL --> TempFile
  YTDL --> FFmpeg
  Updater --> DBCore
  DBCore --> DBStorage
  DBCore --> DBConfig
  BuilderCore --> FSCore
  FSCore --> LocalFS
  FSCore --> S3FS
  Server --> DBCore
  Server --> FSCore
  Server --> FeedConfig
  FeedConfig --> Deps
  Deps --> Hooks
  Hooks --> OPML
  Hooks --> XML
  XML --> Key
  FeedConfig --> MFeed
  FeedConfig --> MLink
  FeedConfig --> MDefaults
  FeedConfig --> MErrors
  Server --> HTML

  %% Styles
  classDef internal fill:#AED6F1,stroke:#21618C,color:#1B2631
  classDef external fill:#F5CBA7,stroke:#D35400,color:#641E16,stroke-dasharray: 5 5
  classDef storage fill:#ABEBC6,stroke:#229954,color:#145A32
  classDef infra fill:#D7BDE2,stroke:#8E44AD,color:#4A235A,stroke-dasharray: 5 5
```
