# artyomsv/marauder architecture

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

- Interactive diagram: https://gitdiagram.com/artyomsv/marauder
- Repository: https://github.com/artyomsv/marauder

## Overview

Marauder is a self-hosted torrent-topic monitor. Users configure topics in the React app; the Go service schedules tracker checks and hands newly found torrent files or magnet links to configured clients, with notifications and durable state. Its documented capabilities also include authentication, cross-tracker search, Sonarr integration, configurable tracker mirrors, and operational observability. The graph follows documented product relationships and visible server/router wiring; several runtime subsystems are represented at their exact enclosing directory because their implementation was not sampled.

Main entry points: [`backend/internal/scheduler/scheduler.go`](https://github.com/artyomsv/marauder/blob/master/backend/internal/scheduler/scheduler.go) (Check scheduler), [`frontend/src/App.tsx`](https://github.com/artyomsv/marauder/blob/master/frontend/src/App.tsx) (Web app), [`backend/internal/plugins/trackers`](https://github.com/artyomsv/marauder/tree/master/backend/internal/plugins/trackers) (Tracker plugins), [`backend/internal/api/router.go`](https://github.com/artyomsv/marauder/blob/master/backend/internal/api/router.go) (HTTP router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Web app<br/>[App.tsx]"]
  node_poster["Topic preview<br/>[PosterImage.tsx]"]
end

subgraph group_service["API and service"]
  node_router["HTTP router<br/>[router.go]"]
  node_topicapi["Topic handlers<br/>[topics.go]"]
  node_auth["Authentication"]
  node_scheduler["Check scheduler<br/>[scheduler.go]"]
  node_sonarrpoll["Sonarr poller<br/>[poller.go]"]
end

subgraph group_monitor["Monitoring plugins"]
  node_trackers["Tracker plugins"]
  node_search["Tracker search<br/>[trackers_search.go]"]
  node_captcha["Captcha login<br/>[engine.go]"]
  node_domains["Domain mirrors<br/>[store.go]"]
  node_clients["Torrent clients"]
  node_flaresolverr["Clearance solver<br/>[client.go]"]
end

subgraph group_state["State and integrations"]
  node_sonarr["Sonarr<br/>[client.go]"]
  node_database[("PostgreSQL state")]
  node_notifiers["Notifier plugins"]
  node_events["Event stream<br/>[bus.go]"]
  node_observability["Metrics and audit<br/>[metrics.go]"]
end

node_user(("User"))
node_cfsolver["CF sidecar<br/>[main.go]"]

node_user -->|"configures topics"| node_app
node_app -.->|"calls API"| node_router
node_router -->|"routes requests"| node_topicapi
node_router -->|"routes sign-in"| node_auth
node_topicapi -.->|"stores topics"| node_database
node_scheduler -->|"checks topics"| node_trackers
node_trackers -->|"hands off torrents"| node_clients
node_app -->|"searches trackers"| node_search
node_search -.->|"queries plugins"| node_trackers
node_trackers -->|"requests login"| node_captcha
node_scheduler -->|"uses mirror settings"| node_domains
node_scheduler -.->|"loads saved state"| node_database
node_scheduler -->|"sends notifications"| node_notifiers
node_scheduler -.->|"publishes updates"| node_events
node_app -.->|"receives live events"| node_events
node_sonarrpoll -->|"polls instances"| node_sonarr
node_sonarrpoll -->|"reads topics"| node_database
node_sonarr -->|"adds monitored topics"| node_scheduler
node_scheduler -->|"records operations"| node_observability
node_trackers -->|"mints clearance"| node_flaresolverr
node_flaresolverr -.->|"solves challenges"| node_cfsolver
node_app -->|"renders previews"| node_poster

click node_app "https://github.com/artyomsv/marauder/blob/master/frontend/src/App.tsx"
click node_poster "https://github.com/artyomsv/marauder/blob/master/frontend/src/components/topics/PosterImage.tsx"
click node_router "https://github.com/artyomsv/marauder/blob/master/backend/internal/api/router.go"
click node_topicapi "https://github.com/artyomsv/marauder/blob/master/backend/internal/api/handlers/topics.go"
click node_auth "https://github.com/artyomsv/marauder/tree/master/backend/internal/auth"
click node_scheduler "https://github.com/artyomsv/marauder/blob/master/backend/internal/scheduler/scheduler.go"
click node_sonarrpoll "https://github.com/artyomsv/marauder/blob/master/backend/internal/sonarr/poller.go"
click node_trackers "https://github.com/artyomsv/marauder/tree/master/backend/internal/plugins/trackers"
click node_search "https://github.com/artyomsv/marauder/blob/master/backend/internal/api/handlers/trackers_search.go"
click node_captcha "https://github.com/artyomsv/marauder/blob/master/backend/internal/plugins/captchalogin/engine.go"
click node_domains "https://github.com/artyomsv/marauder/blob/master/backend/internal/domains/store.go"
click node_clients "https://github.com/artyomsv/marauder/tree/master/backend/internal/plugins/clients"
click node_sonarr "https://github.com/artyomsv/marauder/blob/master/backend/internal/sonarr/client.go"
click node_database "https://github.com/artyomsv/marauder/tree/master/backend/internal/db"
click node_notifiers "https://github.com/artyomsv/marauder/tree/master/backend/internal/plugins/notifiers"
click node_events "https://github.com/artyomsv/marauder/blob/master/backend/internal/events/bus.go"
click node_observability "https://github.com/artyomsv/marauder/blob/master/backend/internal/metrics/metrics.go"
click node_flaresolverr "https://github.com/artyomsv/marauder/blob/master/backend/internal/flaresolverr/client.go"
click node_cfsolver "https://github.com/artyomsv/marauder/blob/master/cfsolver/main.go"

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_app,node_poster,node_user toneBlue
class node_router,node_topicapi,node_auth,node_scheduler,node_sonarrpoll toneAmber
class node_trackers,node_search,node_captcha,node_domains,node_clients,node_flaresolverr toneMint
class node_sonarr,node_database,node_notifiers,node_events,node_observability toneRose
class node_cfsolver toneTeal
```

## Components

### User interface

- [Web app](https://github.com/artyomsv/marauder/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Topic preview](https://github.com/artyomsv/marauder/blob/master/frontend/src/components/topics/PosterImage.tsx): `frontend/src/components/topics/PosterImage.tsx`

### API and service

- [HTTP router](https://github.com/artyomsv/marauder/blob/master/backend/internal/api/router.go): `backend/internal/api/router.go`
- [Topic handlers](https://github.com/artyomsv/marauder/blob/master/backend/internal/api/handlers/topics.go): `backend/internal/api/handlers/topics.go`
- [Authentication](https://github.com/artyomsv/marauder/tree/master/backend/internal/auth): `backend/internal/auth`
- [Check scheduler](https://github.com/artyomsv/marauder/blob/master/backend/internal/scheduler/scheduler.go): `backend/internal/scheduler/scheduler.go`
- [Sonarr poller](https://github.com/artyomsv/marauder/blob/master/backend/internal/sonarr/poller.go): `backend/internal/sonarr/poller.go`

### Monitoring plugins

- [Tracker plugins](https://github.com/artyomsv/marauder/tree/master/backend/internal/plugins/trackers): `backend/internal/plugins/trackers`
- [Tracker search](https://github.com/artyomsv/marauder/blob/master/backend/internal/api/handlers/trackers_search.go): `backend/internal/api/handlers/trackers_search.go`
- [Captcha login](https://github.com/artyomsv/marauder/blob/master/backend/internal/plugins/captchalogin/engine.go): `backend/internal/plugins/captchalogin/engine.go`
- [Domain mirrors](https://github.com/artyomsv/marauder/blob/master/backend/internal/domains/store.go): `backend/internal/domains/store.go`
- [Torrent clients](https://github.com/artyomsv/marauder/tree/master/backend/internal/plugins/clients): `backend/internal/plugins/clients`
- [Clearance solver](https://github.com/artyomsv/marauder/blob/master/backend/internal/flaresolverr/client.go): `backend/internal/flaresolverr/client.go`

### State and integrations

- [Sonarr](https://github.com/artyomsv/marauder/blob/master/backend/internal/sonarr/client.go): `backend/internal/sonarr/client.go`
- [PostgreSQL state](https://github.com/artyomsv/marauder/tree/master/backend/internal/db): `backend/internal/db`
- [Notifier plugins](https://github.com/artyomsv/marauder/tree/master/backend/internal/plugins/notifiers): `backend/internal/plugins/notifiers`
- [Event stream](https://github.com/artyomsv/marauder/blob/master/backend/internal/events/bus.go): `backend/internal/events/bus.go`
- [Metrics and audit](https://github.com/artyomsv/marauder/blob/master/backend/internal/metrics/metrics.go): `backend/internal/metrics/metrics.go`

### Other components

- **User**
- [CF sidecar](https://github.com/artyomsv/marauder/blob/master/cfsolver/main.go): `cfsolver/main.go`

## Connections

- User → Web app: configures topics
- Web app → HTTP router: calls API
- HTTP router → Topic handlers: routes requests (evidence: `backend/internal/api/router.go`)
- HTTP router → Authentication: routes sign-in (evidence: `backend/internal/api/router.go`)
- Topic handlers → PostgreSQL state: stores topics
- Check scheduler → Tracker plugins: checks topics
- Tracker plugins → Torrent clients: hands off torrents
- Web app → Tracker search: searches trackers
- Tracker search → Tracker plugins: queries plugins
- Tracker plugins → Captcha login: requests login (evidence: `backend/internal/plugins/trackers/lostfilm/lostfilm_session.go`)
- Check scheduler → Domain mirrors: uses mirror settings
- Check scheduler → PostgreSQL state: loads saved state
- Check scheduler → Notifier plugins: sends notifications
- Check scheduler → Event stream: publishes updates
- Web app → Event stream: receives live events
- Sonarr poller → Sonarr: polls instances
- Sonarr poller → PostgreSQL state: reads topics
- Sonarr → Check scheduler: adds monitored topics
- Check scheduler → Metrics and audit: records operations
- Tracker plugins → Clearance solver: mints clearance
- Clearance solver → CF sidecar: solves challenges
- Web app → Topic preview: renders previews
