# tfourj/palladium architecture

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

- Interactive diagram: https://gitdiagram.com/tfourj/palladium
- Repository: https://github.com/tfourj/palladium

## Overview

1. **Product shape**
Palladium is a native iOS/iPadOS app, not a server-backed service. The architecture centers on an app target (`Palladium`) plus a separate `ShareExtension` target, with the main executable responsible for all download, processing, storage, and UI orchestration on-device.

2. **Primary user entry points**
The main app UI is SwiftUI-based and organized around a tabbed shell (`Download`, `Console`, `Packages`, `Settings`). `ContentView` and its feature-specific extensions act as the coordination layer between user actions and the underlying services.

3. **Download pipeline**
The core flow is: user submits a media URL → app prepares download options/cookies/packages → Swift layer launches a Python workflow → Python `yt-dlp` logic extracts and downloads media → `ffmpeg` is used for post-processing when needed → the finished file is stored locally and surfaced back to the UI. This is the main architecture boundary in the repo.

4. **Python execution boundary**
The repo embeds Python tooling inside the app rather than calling out to a backend. `PythonFlowRunner` and `PythonScripts` in Swift bridge into the bundled Python code under `Services/Python/palladium_ytdlp`, including `yt_dlp_flow.py` and supporting modules. That Python package is the implementation layer for extraction, package handling, file handling, and WebKit/JS integration.

5. **Media extraction and processing**
`yt-dlp` is the extraction engine, while `ffmpeg` handles conversion, muxing, and related media processing. The `FFmpeg/SwiftFFmpegBridge.swift` and Python-side `ffmpeg_bridge.py` indicate a two-sided integration around the same native capability, with the app mediating between Swift UI and media-processing primitives.

6. **State and domain models**
The app’s user-configurable state is represented in `Models/`: download options, appearance mode, imported cookie files, and link history. These models form the persistent configuration boundary for the UI and the download engine, especially around remembering prior links, user preferences, and authentication-related cookie imports.

7. **Settings and preferences subsystem**
The `Views/Tabs/Settings` subtree shows the app’s configuration surface is split into focused panels: after-download behavior, cookies, download arguments/options, notifications, packages, storage, and interface preferences. This suggests a fairly explicit settings-to-runtime mapping, where user choices directly influence the Python download flow and post-processing behavior.

8. **Console and observability**
`Services/Logging/ConsoleLogStore.swift` plus `ConsoleTabView` imply the app captures and presents runtime logs inside the app rather than relying on external logging. The console is likely the main debugging surface for download failures, package issues, and Python/ffmpeg output.

9. **Shortcuts and automation**
There are two automation hooks: `AppIntents/ShortcutDownloadIntents.swift` for system Shortcuts integration, and `Services/Shortcuts/ShortcutDownloadRequestStore.swift` for persisting requests. This creates an alternate entry path into the same download pipeline without going through the main UI.

10. **Share extension boundary**
The `ShareExtension` target is a separate iOS extension with its own storyboard and entitlements. Its job is to accept shared content from other apps and hand off a URL or related download request into the main app’s workflow, acting as an acquisition front door.

11. **Cookies and authenticated access**
Cookie import support is a first-class subsystem, which matters because media sites often require authenticated or session-aware requests. The cookies settings and `ImportedCookieFile` model indicate the app can ingest browser/exported cookies and pass them into the Python/yt-dlp layer.

12. **Packaging and runtime setup**
The presence of `scripts/install_python_runtime.sh`, `privacy-manifests/python`, and the `Package.resolved` in the Xcode workspace indicates this is a self-contained mobile build that bundles runtime dependencies and declares privacy metadata for embedded Python-related components. The build pipeline is iOS-centric, with `build_ipa.sh` and GitHub Actions used to produce distributable IPAs.

13. **What to draw as the main architecture**
A useful diagram would show three major zones: the SwiftUI app shell and settings UI; the service layer that manages logging, shortcuts, storage, and Python invocation; and the embedded Python/media-processing runtime built around `yt-dlp` and `ffmpeg`. The share extension and App Intents should be shown as alternate ingress paths into the same central download workflow.

Main entry points: [`Palladium/Views/ContentView+DownloadFlow.swift`](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+DownloadFlow.swift) (Download flow), [`Palladium/Views/ContentView.swift`](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView.swift) (Content view), [`Palladium/Models/DownloadOptions.swift`](https://github.com/tfourj/palladium/blob/main/Palladium/Models/DownloadOptions.swift) (App models), [`Palladium/Services/Python/PythonFlowRunner.swift`](https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/PythonFlowRunner.swift) (Python runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["iOS App"]
  node_node_app(("Palladium app<br/>SwiftUI app<br/>[PalladiumApp.swift]"))
  node_node_content["Content view<br/>UI coordinator<br/>[ContentView.swift]"]
  node_node_download_tab["Download tab<br/>tab UI"]
  node_node_console_tab["Console tab<br/>log UI"]
  node_node_packages_tab["Packages tab<br/>tab UI"]
  node_node_settings_tab["Settings tab<br/>settings shell"]
  node_node_models[("App models<br/>state models")]
  node_node_download_flow["Download flow<br/>orchestration"]
  node_node_preferences["Preferences<br/>settings logic"]
  node_node_history["History<br/>state logic"]
  node_node_cookies["Cookies<br/>auth settings"]
  node_node_postdownload["Post-download<br/>runtime policy"]
  node_node_storage["Storage"]
  node_node_notifications["Notifications<br/>settings logic"]
  node_node_shortcuts["Shortcuts<br/>app intents"]
  node_node_shortcut_store["Request store<br/>request persistence"]
  node_node_console_store["Log store<br/>logging store"]
end

subgraph group_group_runtime["Embedded Runtime"]
  node_node_python_runner["Python runner<br/>bridge"]
  node_node_python_scripts["Python scripts<br/>script catalog"]
  node_node_ytdlp_flow["yt-dlp flow<br/>python flow<br/>[yt_dlp_flow.py]"]
  node_node_py_pkg["palladium_ytdlp<br/>python package<br/>[__init__.py]"]
  node_node_ffmpeg_bridge["FFmpeg bridge<br/>native bridge"]
end

subgraph group_group_delivery["Extension & Build"]
  node_node_share_ext["Share extension<br/>iOS extension"]
  node_node_build_script["IPA build<br/>build script<br/>[build_ipa.sh]"]
  node_node_python_runtime["Python runtime setup<br/>install script"]
end

node_node_app -->|"launches"| node_node_content
node_node_content -->|"shows"| node_node_download_tab
node_node_content -->|"shows"| node_node_console_tab
node_node_content -->|"shows"| node_node_packages_tab
node_node_content -->|"shows"| node_node_settings_tab
node_node_content -->|"orchestrates"| node_node_download_flow
node_node_download_flow -->|"reads/writes"| node_node_models
node_node_download_flow -->|"invokes"| node_node_python_runner
node_node_download_flow -->|"uses"| node_node_ffmpeg_bridge
node_node_download_flow -->|"hands off"| node_node_postdownload
node_node_preferences -->|"updates"| node_node_models
node_node_history -->|"updates"| node_node_models
node_node_cookies -->|"updates"| node_node_models
node_node_storage -->|"updates"| node_node_models
node_node_notifications -->|"updates"| node_node_models
node_node_shortcuts -->|"persists"| node_node_shortcut_store
node_node_shortcuts -->|"triggers"| node_node_download_flow
node_node_console_tab -->|"reads"| node_node_console_store
node_node_python_runner -->|"loads"| node_node_python_scripts
node_node_python_runner -->|"executes"| node_node_ytdlp_flow
node_node_ytdlp_flow -->|"depends on"| node_node_py_pkg
node_node_py_pkg -->|"integrates"| node_node_ffmpeg_bridge
node_node_share_ext -.->|"hands off to"| node_node_download_flow
node_node_share_ext -.->|"uses"| node_node_models
node_node_python_runtime -.->|"prepares"| node_node_python_runner
node_node_build_script -.->|"packages"| node_node_python_runtime

click node_node_app "https://github.com/tfourj/palladium/blob/main/Palladium/PalladiumApp.swift"
click node_node_content "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView.swift"
click node_node_download_tab "https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/DownloadTabView.swift"
click node_node_console_tab "https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/ConsoleTabView.swift"
click node_node_packages_tab "https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/PackagesTabView.swift"
click node_node_settings_tab "https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/SettingsTabView.swift"
click node_node_models "https://github.com/tfourj/palladium/blob/main/Palladium/Models/DownloadOptions.swift"
click node_node_download_flow "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+DownloadFlow.swift"
click node_node_preferences "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Preferences.swift"
click node_node_history "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+History.swift"
click node_node_cookies "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Cookies.swift"
click node_node_postdownload "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+PostDownload.swift"
click node_node_storage "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Storage.swift"
click node_node_notifications "https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Notifications.swift"
click node_node_shortcuts "https://github.com/tfourj/palladium/blob/main/Palladium/AppIntents/ShortcutDownloadIntents.swift"
click node_node_shortcut_store "https://github.com/tfourj/palladium/blob/main/Palladium/Services/Shortcuts/ShortcutDownloadRequestStore.swift"
click node_node_console_store "https://github.com/tfourj/palladium/blob/main/Palladium/Services/Logging/ConsoleLogStore.swift"
click node_node_python_runner "https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/PythonFlowRunner.swift"
click node_node_python_scripts "https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/PythonScripts.swift"
click node_node_ytdlp_flow "https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/yt_dlp_flow.py"
click node_node_py_pkg "https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/palladium_ytdlp/__init__.py"
click node_node_ffmpeg_bridge "https://github.com/tfourj/palladium/blob/main/Palladium/Services/FFmpeg/SwiftFFmpegBridge.swift"
click node_node_share_ext "https://github.com/tfourj/palladium/blob/main/ShareExtension/ShareViewController.swift"
click node_node_build_script "https://github.com/tfourj/palladium/blob/main/build_ipa.sh"
click node_node_python_runtime "https://github.com/tfourj/palladium/blob/main/scripts/install_python_runtime.sh"

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_node_app,node_node_content,node_node_download_tab,node_node_console_tab,node_node_packages_tab,node_node_settings_tab,node_node_models,node_node_download_flow,node_node_preferences,node_node_history,node_node_cookies,node_node_postdownload,node_node_storage,node_node_notifications,node_node_shortcuts,node_node_shortcut_store,node_node_console_store toneBlue
class node_node_python_runner,node_node_python_scripts,node_node_ytdlp_flow,node_node_py_pkg,node_node_ffmpeg_bridge toneAmber
class node_node_share_ext,node_node_build_script,node_node_python_runtime toneMint
```

## Components

### iOS App

Main SwiftUI app target and feature surfaces.

- [Palladium app](https://github.com/tfourj/palladium/blob/main/Palladium/PalladiumApp.swift): SwiftUI app · Main iOS/iPadOS executable entry point. · `Palladium/PalladiumApp.swift`
- [Content view](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView.swift): UI coordinator · Coordinates tabs and feature-specific app flows. · `Palladium/Views/ContentView.swift`
- [Download tab](https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/DownloadTabView.swift): tab UI · User entry for starting downloads. · `Palladium/Views/Tabs/DownloadTabView.swift`
- [Console tab](https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/ConsoleTabView.swift): log UI · In-app runtime log and troubleshooting surface. · `Palladium/Views/Tabs/ConsoleTabView.swift`
- [Packages tab](https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/PackagesTabView.swift): tab UI · Package visibility and setup controls. · `Palladium/Views/Tabs/PackagesTabView.swift`
- [Settings tab](https://github.com/tfourj/palladium/blob/main/Palladium/Views/Tabs/SettingsTabView.swift): settings shell · Container for app preferences panels. · `Palladium/Views/Tabs/SettingsTabView.swift`
- [App models](https://github.com/tfourj/palladium/blob/main/Palladium/Models/DownloadOptions.swift): state models · Persistent app state for options, appearance, cookies, and history. · `Palladium/Models/DownloadOptions.swift`
- [Download flow](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+DownloadFlow.swift): orchestration · Coordinates URL intake, options, Python invocation, and completion handling. · `Palladium/Views/ContentView+DownloadFlow.swift`
- [Preferences](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Preferences.swift): settings logic · Maps UI preferences to runtime behavior. · `Palladium/Views/ContentView+Preferences.swift`
- [History](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+History.swift): state logic · Tracks previously handled links. · `Palladium/Views/ContentView+History.swift`
- [Cookies](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Cookies.swift): auth settings · Imports and applies cookie files for authenticated downloads. · `Palladium/Views/ContentView+Cookies.swift`
- [Post-download](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+PostDownload.swift): runtime policy · Handles after-download actions and file handoff. · `Palladium/Views/ContentView+PostDownload.swift`
- [Storage](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Storage.swift): storage settings · Controls local file locations and retention behavior. · `Palladium/Views/ContentView+Storage.swift`
- [Notifications](https://github.com/tfourj/palladium/blob/main/Palladium/Views/ContentView+Notifications.swift): settings logic · Notification preferences and delivery hooks. · `Palladium/Views/ContentView+Notifications.swift`
- [Shortcuts](https://github.com/tfourj/palladium/blob/main/Palladium/AppIntents/ShortcutDownloadIntents.swift): app intents · System Shortcuts entry into the download pipeline. · `Palladium/AppIntents/ShortcutDownloadIntents.swift`
- [Request store](https://github.com/tfourj/palladium/blob/main/Palladium/Services/Shortcuts/ShortcutDownloadRequestStore.swift): request persistence · Persists shortcut-triggered download requests. · `Palladium/Services/Shortcuts/ShortcutDownloadRequestStore.swift`
- [Log store](https://github.com/tfourj/palladium/blob/main/Palladium/Services/Logging/ConsoleLogStore.swift): logging store · Captures app and runtime output for the console tab. · `Palladium/Services/Logging/ConsoleLogStore.swift`

### Embedded Runtime

On-device Python and media-processing boundary.

- [Python runner](https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/PythonFlowRunner.swift): bridge · Swift boundary for invoking bundled Python workflows. · `Palladium/Services/Python/PythonFlowRunner.swift`
- [Python scripts](https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/PythonScripts.swift): script catalog · Declares bundled Python entry scripts and resources. · `Palladium/Services/Python/PythonScripts.swift`
- [yt-dlp flow](https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/yt_dlp_flow.py): python flow · Top-level Python workflow for extraction and download. · `Palladium/Services/Python/yt_dlp_flow.py`
- [palladium_ytdlp](https://github.com/tfourj/palladium/blob/main/Palladium/Services/Python/palladium_ytdlp/__init__.py): python package · Bundled Python package implementing extraction, file, package, and JS helpers. · `Palladium/Services/Python/palladium_ytdlp/__init__.py`
- [FFmpeg bridge](https://github.com/tfourj/palladium/blob/main/Palladium/Services/FFmpeg/SwiftFFmpegBridge.swift): native bridge · Swift side integration with native ffmpeg capabilities. · `Palladium/Services/FFmpeg/SwiftFFmpegBridge.swift`

### Extension & Build

Ingress extension and build/distribution tooling.

- [Share extension](https://github.com/tfourj/palladium/blob/main/ShareExtension/ShareViewController.swift): iOS extension · Separate target that accepts shared content and hands off requests. · `ShareExtension/ShareViewController.swift`
- [IPA build](https://github.com/tfourj/palladium/blob/main/build_ipa.sh): build script · Automates archive and distributable IPA creation. · `build_ipa.sh`
- [Python runtime setup](https://github.com/tfourj/palladium/blob/main/scripts/install_python_runtime.sh): install script · Installs or prepares the embedded Python runtime. · `scripts/install_python_runtime.sh`

## Connections

- Palladium app → Content view: launches · App entry presents the main SwiftUI shell.
- Content view → Download tab: shows · Download entry point is one of the primary tabs.
- Content view → Console tab: shows · Console surface is embedded in the shell.
- Content view → Packages tab: shows · Packages management is available from the shell.
- Content view → Settings tab: shows · Settings panels are grouped under a tab.
- Content view → Download flow: orchestrates · Feature extensions coordinate the end-to-end download flow.
- Download flow → App models: reads/writes · Download options, history, cookies, and storage state feed the flow.
- Download flow → Python runner: invokes · Swift bridge launches bundled Python processing.
- Download flow → FFmpeg bridge: uses · Media post-processing may require ffmpeg integration.
- Download flow → Post-download: hands off · Completed files are routed to post-download handling.
- Preferences → App models: updates · User preferences are persisted in app state models.
- History → App models: updates · Visited links are stored in history state.
- Cookies → App models: updates · Imported cookie files are tracked as state.
- Storage → App models: updates · Storage choices map into persisted configuration.
- Notifications → App models: updates · Notification settings are persisted.
- Shortcuts → Request store: persists · Shortcut requests are stored for later processing.
- Shortcuts → Download flow: triggers · Automation enters the same download pipeline as the UI.
- Console tab → Log store: reads · Console UI presents captured runtime logs.
- Python runner → Python scripts: loads · Runner selects bundled script entry points.
- Python runner → yt-dlp flow: executes · Runner enters the main Python download workflow.
- yt-dlp flow → palladium_ytdlp: depends on · The flow relies on the bundled Python package implementation.
- palladium_ytdlp → FFmpeg bridge: integrates · Python side includes media-processing bridge support.
- Share extension → Download flow: hands off to · Shared content becomes a download request for the main app.
- Share extension → App models: uses · Extension may pass along or derive request state.
- Python runtime setup → Python runner: prepares · Runtime setup supports the embedded Python bridge.
- IPA build → Python runtime setup: packages · Build tooling assembles the runtime into the distributable app.
