# eddie-dk1/threadgoon architecture

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

- Interactive diagram: https://gitdiagram.com/eddie-dk1/threadgoon
- Repository: https://github.com/eddie-dk1/threadgoon

## Overview

Threadgoon is a macOS thread-search and attachment-download application, with a supported terminal interface. The main workflow is search 4chan catalogs, optionally inspect threads and attachments for exact matches, confirm a download set, then queue and resume downloads; users can also monitor threads for new files. The graph includes the SwiftUI client, Python engine, shared persistence and configuration, plus the documented watch and terminal capabilities. Source excerpts are partial, so uncertain internal links are omitted; README statements support the cross-process relationship.

Main entry points: [`threadgoon/database.py`](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/database.py) (Workspace database), [`threadgoon/controller.py`](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/controller.py) (Command controller), [`native/Sources/Threadgoon/ContentView.swift`](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/ContentView.swift) (SwiftUI window), [`threadgoon/watcher.py`](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/watcher.py) (Thread watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["macOS application"]
  node_swiftui["SwiftUI window<br/>[ContentView.swift]"]
  node_appmodel["UI state<br/>[AppModel.swift]"]
  node_engineclient["Engine process client<br/>[EngineClient.swift]"]
  node_thumbnails["Thread thumbnails"]
  node_queueviews["Queue views<br/>[QueueViews.swift]"]
  node_utilityviews["Utility views<br/>[UtilityViews.swift]"]
  node_wiremodels["Wire models<br/>[Models.swift]"]
end

subgraph group_engine["Python engine"]
  node_bridge["Engine protocol<br/>[bridge.py]"]
  node_controller["Command controller<br/>[controller.py]"]
  node_scanner["Catalog and thread scan<br/>[scanner.py]"]
  node_api["4chan API client<br/>[api.py]"]
  node_downloads["Download manager<br/>[downloader.py]"]
  node_watcher["Thread watcher<br/>[watcher.py]"]
  node_preview["Preview helpers<br/>[preview.py]"]
end

subgraph group_data["Workspace data"]
  node_repository[("Workspace database<br/>[database.py]")]
  node_config["Application settings<br/>[config.py]"]
  node_paths["Workspace paths<br/>[paths.py]"]
  node_domain["Domain records<br/>[models.py]"]
  node_logging["Logging setup<br/>[logging_config.py]"]
end

subgraph group_terminal["Terminal interface"]
  node_textual["Terminal interface<br/>[app.py]"]
  node_cli["Terminal commands<br/>[cli.py]"]
end

node_user(("User"))
node_fourchan(("4chan service"))
node_filesystem[("Workspace files")]

node_user -->|"uses"| node_swiftui
node_swiftui -->|"displays state"| node_appmodel
node_swiftui -->|"renders"| node_thumbnails
node_swiftui -->|"renders"| node_queueviews
node_swiftui -->|"renders"| node_utilityviews
node_appmodel -->|"sends commands"| node_engineclient
node_engineclient -->|"starts Python engine"| node_bridge
node_engineclient -->|"frames messages"| node_wiremodels
node_bridge -->|"dispatches commands"| node_controller
node_controller -->|"runs searches"| node_scanner
node_controller -->|"controls jobs"| node_downloads
node_controller -->|"manages watches"| node_watcher
node_scanner -->|"fetches metadata"| node_api
node_scanner -->|"reads and stores scans"| node_repository
node_api -->|"requests JSON API"| node_fourchan
node_api -->|"caches responses"| node_repository
node_downloads -->|"updates jobs"| node_repository
node_downloads -->|"fetches media"| node_fourchan
node_downloads -->|"writes files"| node_filesystem
node_watcher -->|"polls threads"| node_api
node_watcher -->|"updates watches"| node_repository
node_watcher -->|"queues new files"| node_downloads
node_watcher -->|"parses threads"| node_scanner
node_preview -->|"uses scan records"| node_scanner
node_controller -->|"uses settings"| node_config
node_config -->|"validates workspace"| node_paths
node_controller -->|"reads and writes state"| node_repository
node_repository -->|"stores records"| node_domain
node_repository -->|"persists SQLite and cache"| node_filesystem
node_paths -->|"validates locations"| node_filesystem
node_user -->|"runs commands"| node_cli
node_cli -->|"opens interface"| node_textual
node_textual -->|"submits operations"| node_controller
node_textual -->|"shows history"| node_repository
node_cli -->|"loads settings"| node_config
node_cli -->|"configures logs"| node_logging

click node_swiftui "https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/ContentView.swift"
click node_appmodel "https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/AppModel.swift"
click node_engineclient "https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/EngineClient.swift"
click node_thumbnails "https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/ThumbnailView.swift"
click node_queueviews "https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/QueueViews.swift"
click node_utilityviews "https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/UtilityViews.swift"
click node_wiremodels "https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/ThreadgoonCore/Models.swift"
click node_bridge "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/bridge.py"
click node_controller "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/controller.py"
click node_scanner "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/scanner.py"
click node_api "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/api.py"
click node_downloads "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/downloader.py"
click node_watcher "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/watcher.py"
click node_preview "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/preview.py"
click node_textual "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/app.py"
click node_cli "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/cli.py"
click node_repository "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/database.py"
click node_config "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/config.py"
click node_paths "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/paths.py"
click node_domain "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/models.py"
click node_logging "https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/logging_config.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_swiftui,node_appmodel,node_engineclient,node_thumbnails,node_queueviews,node_utilityviews,node_wiremodels,node_user toneBlue
class node_bridge,node_controller,node_scanner,node_api,node_downloads,node_watcher,node_preview,node_filesystem toneAmber
class node_repository,node_config,node_paths,node_domain,node_logging toneMint
class node_textual,node_cli toneRose
class node_fourchan toneIndigo
```

## Components

### macOS application

- [SwiftUI window](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/ContentView.swift): `native/Sources/Threadgoon/ContentView.swift`
- [UI state](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/AppModel.swift): `native/Sources/Threadgoon/AppModel.swift`
- [Engine process client](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/EngineClient.swift): `native/Sources/Threadgoon/EngineClient.swift`
- [Thread thumbnails](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/ThumbnailView.swift): `native/Sources/Threadgoon/ThumbnailView.swift`
- [Queue views](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/QueueViews.swift): `native/Sources/Threadgoon/QueueViews.swift`
- [Utility views](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/Threadgoon/UtilityViews.swift): `native/Sources/Threadgoon/UtilityViews.swift`
- [Wire models](https://github.com/eddie-dk1/threadgoon/blob/main/native/Sources/ThreadgoonCore/Models.swift): `native/Sources/ThreadgoonCore/Models.swift`

### Python engine

- [Engine protocol](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/bridge.py): `threadgoon/bridge.py`
- [Command controller](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/controller.py): `threadgoon/controller.py`
- [Catalog and thread scan](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/scanner.py): `threadgoon/scanner.py`
- [4chan API client](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/api.py): `threadgoon/api.py`
- [Download manager](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/downloader.py): `threadgoon/downloader.py`
- [Thread watcher](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/watcher.py): `threadgoon/watcher.py`
- [Preview helpers](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/preview.py): `threadgoon/preview.py`

### Workspace data

- [Workspace database](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/database.py): `threadgoon/database.py`
- [Application settings](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/config.py): `threadgoon/config.py`
- [Workspace paths](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/paths.py): `threadgoon/paths.py`
- [Domain records](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/models.py): `threadgoon/models.py`
- [Logging setup](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/logging_config.py): `threadgoon/logging_config.py`

### Terminal interface

- [Terminal interface](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/app.py): `threadgoon/app.py`
- [Terminal commands](https://github.com/eddie-dk1/threadgoon/blob/main/threadgoon/cli.py): `threadgoon/cli.py`

### Other components

- **User**
- **4chan service**
- **Workspace files**

## Connections

- User → SwiftUI window: uses (evidence: `README.md`)
- SwiftUI window → UI state: displays state (evidence: `native/Sources/Threadgoon/ContentView.swift`)
- SwiftUI window → Thread thumbnails: renders (evidence: `native/Sources/Threadgoon/ContentView.swift`)
- SwiftUI window → Queue views: renders (evidence: `native/Sources/Threadgoon/QueueViews.swift`)
- SwiftUI window → Utility views: renders (evidence: `native/Sources/Threadgoon/UtilityViews.swift`)
- UI state → Engine process client: sends commands (evidence: `native/Sources/Threadgoon/AppModel.swift`)
- Engine process client → Engine protocol: starts Python engine (evidence: `README.md`)
- Engine process client → Wire models: frames messages (evidence: `native/Sources/Threadgoon/EngineClient.swift`)
- Engine protocol → Command controller: dispatches commands (evidence: `threadgoon/bridge.py`)
- Command controller → Catalog and thread scan: runs searches (evidence: `threadgoon/controller.py`)
- Command controller → Download manager: controls jobs (evidence: `threadgoon/controller.py`)
- Command controller → Thread watcher: manages watches (evidence: `threadgoon/controller.py`)
- Catalog and thread scan → 4chan API client: fetches metadata (evidence: `threadgoon/scanner.py`)
- Catalog and thread scan → Workspace database: reads and stores scans (evidence: `threadgoon/scanner.py`)
- 4chan API client → 4chan service: requests JSON API (evidence: `README.md`)
- 4chan API client → Workspace database: caches responses (evidence: `threadgoon/api.py`)
- Download manager → Workspace database: updates jobs (evidence: `threadgoon/downloader.py`)
- Download manager → 4chan service: fetches media (evidence: `threadgoon/downloader.py`)
- Download manager → Workspace files: writes files (evidence: `README.md`)
- Thread watcher → 4chan API client: polls threads (evidence: `threadgoon/watcher.py`)
- Thread watcher → Workspace database: updates watches (evidence: `threadgoon/watcher.py`)
- Thread watcher → Download manager: queues new files (evidence: `threadgoon/watcher.py`)
- Thread watcher → Catalog and thread scan: parses threads (evidence: `threadgoon/watcher.py`)
- Preview helpers → Catalog and thread scan: uses scan records (evidence: `threadgoon/preview.py`)
- Command controller → Application settings: uses settings (evidence: `threadgoon/controller.py`)
- Application settings → Workspace paths: validates workspace (evidence: `threadgoon/config.py`)
- Command controller → Workspace database: reads and writes state (evidence: `threadgoon/controller.py`)
- Workspace database → Domain records: stores records (evidence: `threadgoon/database.py`)
- Workspace database → Workspace files: persists SQLite and cache (evidence: `README.md`)
- Workspace paths → Workspace files: validates locations (evidence: `threadgoon/paths.py`)
- User → Terminal commands: runs commands (evidence: `README.md`)
- Terminal commands → Terminal interface: opens interface (evidence: `threadgoon/cli.py`)
- Terminal interface → Command controller: submits operations (evidence: `threadgoon/app.py`)
- Terminal interface → Workspace database: shows history (evidence: `threadgoon/app.py`)
- Terminal commands → Application settings: loads settings (evidence: `threadgoon/cli.py`)
- Terminal commands → Logging setup: configures logs (evidence: `threadgoon/cli.py`)
