# arcadia-solutions/arcadia architecture

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

- Interactive diagram: https://gitdiagram.com/arcadia-solutions/arcadia
- Repository: https://github.com/arcadia-solutions/arcadia

## Overview

1. **Repository shape**
   - This is a multi-crate Rust monorepo plus a separate TypeScript/Vue frontend.
   - The main runtime pieces are: `backend/api`, `backend/storage`, `tracker/arcadia_tracker`, `backend/periodic-tasks`, `frontend`, and a small shared Rust crate in `shared`.

2. **User-facing application boundary**
   - The browser-facing product is a client-side rendered Vue 3 SPA in `frontend`.
   - It does not own business logic; it consumes the Rust API through a generated OpenAPI client under `frontend/src/services/api-schema`.
   - The frontend is organized around domain-heavy views/components for torrents, title groups, forums, users, staff tools, subscriptions, notifications, and search.

3. **Main application backend**
   - `backend/api` is the central HTTP service for the site.
   - Its `src/handlers` tree is split by domain: auth, users, torrents, title groups, forums, wiki, search, notifications, donations, shop, staff moderation, settings, external DB lookups, etc.
   - `routes.rs`, middleware, and services wire those handlers into a secure web API with auth enforcement and side effects.

4. **Data access layer**
   - `backend/storage` is the persistence boundary for the API and periodic jobs.
   - It contains:
     - database connection management,
     - typed models,
     - repository modules per domain,
     - a few domain services such as shop/promotion/bonus points,
     - utility code for torrent/tag/user-badge logic.
   - The presence of `.sqlx` artifacts and migrations shows SQLx-backed, compile-time checked SQL with a relational database as the core datastore.
   - Redis support also exists in `backend/storage/src/redis`, so some state is cached or queued outside the main DB.

5. **Tracker service**
   - `tracker/arcadia_tracker` is a separate service for BitTorrent announce traffic.
   - It has its own routes, middleware, scheduler, metrics, and announce handler path.
   - This service is distinct from the web API: it handles peer/user/torrent announce updates rather than general site CRUD.

6. **Shared tracker/domain primitives**
   - `shared` contains common code used across services, especially tracker-facing models and telemetry/error helpers.
   - This crate reduces duplication for types such as peer, torrent, user, and announce update payloads.
   - It acts as a boundary layer between the tracker and other Rust components.

7. **Background/maintenance processing**
   - `backend/periodic-tasks` is a standalone worker crate for scheduled jobs.
   - Its task modules include bonus points, expired warnings, inactive users, materialized views, peers, seeding size, torrents, user badges, and user classes.
   - This indicates the platform has non-interactive maintenance logic that continuously reconciles state in the database.

8. **Cross-system integrations**
   - The API includes dedicated services for external dependencies: email, IRC, image hosting, image processing, and external metadata lookups.
   - The external DB handlers suggest live enrichment from services like MusicBrainz, TMDB, Comic Vine, and ISBN-related sources.
   - `kiwiirc` is an auxiliary integration for embedded IRC chat, likely consuming the site’s IRC auth/account data.

9. **Core data flows**
   - Browser → frontend SPA → backend API.
   - Backend API → storage repositories/services → SQL database and Redis.
   - Backend API → external services for metadata, notifications, email, IRC, and image handling.
   - Tracker client announce traffic → tracker service → storage/peer-state updates.
   - Periodic tasks → storage/database to recompute aggregates and enforce lifecycle rules.

10. **Auth and permissions**
   - Authentication is a major architectural boundary in the API.
   - There are login/refresh/logout flows, IRC auth, API keys, user applications, permission editing, and middleware-based access control.
   - Many endpoints are staff-only or class/permission-gated, which is reflected by the large number of moderation and admin handlers.

11. **Domain modules**
   - The app’s domain model is broad: artists, series, title groups, torrents, torrent requests, collages, forums, wiki, conversations, gifts, donations, badges, shop, notifications, subscriptions, and staff moderation.
   - Most of these are first-class subsystems with dedicated CRUD and relationship-management endpoints, and corresponding storage repositories/models.

12. **Search and read-model style endpoints**
   - Search is its own subsystem, not just a database query helper.
   - There are separate endpoints for users, torrents, forum, wiki, conversations, series, collages, title-group metadata, and requests.
   - This implies optimized read models and query-specific repository logic rather than a single generic search index abstraction.

13. **Observability and ops**
   - The repo includes OpenTelemetry configuration artifacts and explicit metrics modules in backend services.
   - CI/CD is container-oriented: GitHub workflows, Dockerfiles, devcontainer config, and SQLx offline metadata are all present.
   - Docs are maintained as a separate book in `docs/`, suggesting deploy/run/backup/testing are part of the intended operational story.

14. **Architecture diagram guidance**
   - Draw three main runtime boxes: web SPA, web API/storage backend, and tracker service.
   - Add a separate background-worker box for periodic tasks.
   - Show the database and Redis as shared persistence/infrastructure beneath API, tracker, and workers.
   - Show outbound integrations from the API to email/IRC/image/external-metadata services.
   - Treat `shared` as a compile-time library boundary, not a deployed service.

Main entry points: [`backend/api/src/handlers`](https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/handlers) (Handlers), [`backend/api/src/services`](https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/services) (API Services), [`frontend`](https://github.com/arcadia-solutions/arcadia/tree/main/frontend) (Vue SPA), [`backend/api/src/main.rs`](https://github.com/arcadia-solutions/arcadia/blob/main/backend/api/src/main.rs) (API Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_spa["Vue SPA<br/>client app"]
  node_frontend_api_client["API Client<br/>generated client"]
end

subgraph group_backend_api["Web API"]
  node_api_entry["API Server<br/>http service<br/>[main.rs]"]
  node_api_routes["Routes<br/>router<br/>[routes.rs]"]
  node_api_handlers["Handlers<br/>domain endpoints"]
  node_api_services["API Services<br/>integration layer"]
  node_api_middleware["Auth Middleware<br/>access control"]
end

subgraph group_backend_storage["Storage"]
  node_storage_models["Models"]
  node_storage_repos["Repositories<br/>db access"]
  node_storage_services["Store Services<br/>domain services"]
  node_storage_redis[("Redis<br/>cache/queue")]
end

subgraph group_tracker["Tracker"]
  node_tracker_entry["Tracker<br/>announce service<br/>[main.rs]"]
  node_tracker_routes["Tracker Routes<br/>router<br/>[routes.rs]"]
  node_announce_handler["Announce Handler<br/>peer updates<br/>[handle_announce.rs]"]
  node_tracker_services["Tracker Services<br/>announce logic"]
end

subgraph group_worker["Background Jobs"]
  node_worker_sched["Scheduler<br/>job runner<br/>[scheduler.rs]"]
  node_worker_tasks["Periodic Tasks<br/>maintenance jobs"]
end

subgraph group_infra["Infrastructure"]
  node_db[("Relational DB<br/>primary datastore")]
  node_redis[("Redis<br/>shared cache")]
  node_external["External Systems<br/>integrations"]
end

subgraph group_shared_lib["Shared Lib"]
  node_shared_tracker["Shared Primitives<br/>shared crate"]
end

node_frontend_spa -->|"uses"| node_frontend_api_client
node_frontend_spa -->|"HTTP"| node_api_entry
node_api_entry -->|"wires"| node_api_routes
node_api_routes -->|"dispatches"| node_api_handlers
node_api_handlers -->|"protected by"| node_api_middleware
node_api_handlers -->|"calls"| node_api_services
node_api_handlers -->|"reads/writes"| node_storage_repos
node_api_services -->|"delegates"| node_storage_services
node_storage_repos -->|"maps"| node_storage_models
node_storage_repos -->|"SQLx"| node_db
node_storage_services -->|"queries"| node_db
node_api_services -->|"uses"| node_redis
node_storage_redis -->|"backs"| node_redis
node_tracker_entry -->|"wires"| node_tracker_routes
node_tracker_routes -->|"dispatches"| node_announce_handler
node_announce_handler -->|"calls"| node_tracker_services
node_tracker_services -->|"updates"| node_db
node_tracker_entry -.->|"imports"| node_shared_tracker
node_api_entry -.->|"imports"| node_shared_tracker
node_worker_sched -->|"runs"| node_worker_tasks
node_worker_tasks -->|"reconciles"| node_db
node_worker_tasks -->|"touches"| node_redis
node_api_services -->|"calls out"| node_external
node_frontend_spa -->|"embedded chat"| node_external

click node_frontend_spa "https://github.com/arcadia-solutions/arcadia/tree/main/frontend"
click node_frontend_api_client "https://github.com/arcadia-solutions/arcadia/tree/main/frontend/src/services/api-schema"
click node_api_entry "https://github.com/arcadia-solutions/arcadia/blob/main/backend/api/src/main.rs"
click node_api_routes "https://github.com/arcadia-solutions/arcadia/blob/main/backend/api/src/routes.rs"
click node_api_handlers "https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/handlers"
click node_api_services "https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/services"
click node_api_middleware "https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/middlewares"
click node_storage_models "https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/models"
click node_storage_repos "https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/repositories"
click node_storage_services "https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/services"
click node_storage_redis "https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/redis"
click node_tracker_entry "https://github.com/arcadia-solutions/arcadia/blob/main/tracker/arcadia_tracker/src/main.rs"
click node_tracker_routes "https://github.com/arcadia-solutions/arcadia/blob/main/tracker/arcadia_tracker/src/routes.rs"
click node_announce_handler "https://github.com/arcadia-solutions/arcadia/blob/main/tracker/arcadia_tracker/src/announce/handlers/announce/handle_announce.rs"
click node_tracker_services "https://github.com/arcadia-solutions/arcadia/tree/main/tracker/arcadia_tracker/src/services"
click node_worker_sched "https://github.com/arcadia-solutions/arcadia/blob/main/backend/periodic-tasks/src/periodic_tasks/scheduler.rs"
click node_worker_tasks "https://github.com/arcadia-solutions/arcadia/tree/main/backend/periodic-tasks/src/periodic_tasks"
click node_shared_tracker "https://github.com/arcadia-solutions/arcadia/tree/main/shared/src/tracker"
click node_external "https://github.com/arcadia-solutions/arcadia/tree/main/kiwiirc"

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_frontend_spa,node_frontend_api_client,node_shared_tracker toneBlue
class node_api_entry,node_api_routes,node_api_handlers,node_api_services,node_api_middleware toneAmber
class node_storage_models,node_storage_repos,node_storage_services,node_storage_redis toneMint
class node_tracker_entry,node_tracker_routes,node_announce_handler,node_tracker_services toneRose
class node_worker_sched,node_worker_tasks toneIndigo
class node_db,node_redis,node_external toneTeal
```

## Components

### Frontend

Client-side Vue SPA and generated API client

- [Vue SPA](https://github.com/arcadia-solutions/arcadia/tree/main/frontend): client app · Client-side rendered browser application · `frontend`
- [API Client](https://github.com/arcadia-solutions/arcadia/tree/main/frontend/src/services/api-schema): generated client · OpenAPI-generated Rust/TS client used by the SPA · `frontend/src/services/api-schema`

### Web API

HTTP service, auth, handlers, and outbound integrations

- [API Server](https://github.com/arcadia-solutions/arcadia/blob/main/backend/api/src/main.rs): http service · Main backend web service entrypoint · `backend/api/src/main.rs`
- [Routes](https://github.com/arcadia-solutions/arcadia/blob/main/backend/api/src/routes.rs): router · HTTP route wiring and endpoint composition · `backend/api/src/routes.rs`
- [Handlers](https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/handlers): domain endpoints · Domain split request handlers for auth, torrents, users, forums, wiki, search, staff, and more · `backend/api/src/handlers`
- [API Services](https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/services): integration layer · Outbound services for auth, email, IRC, images, metadata, and announces · `backend/api/src/services`
- [Auth Middleware](https://github.com/arcadia-solutions/arcadia/tree/main/backend/api/src/middlewares): access control · Authentication and side-effect middleware enforcing permissions · `backend/api/src/middlewares`

### Storage

SQLx-backed persistence boundary and Redis support

- [Models](https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/models): db models · Typed relational models for site domains · `backend/storage/src/models`
- [Repositories](https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/repositories): db access · Domain repositories wrapping SQLx queries · `backend/storage/src/repositories`
- [Store Services](https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/services): domain services · Storage-side shop, promotion, and bonus-point logic · `backend/storage/src/services`
- [Redis](https://github.com/arcadia-solutions/arcadia/tree/main/backend/storage/src/redis): cache/queue · Redis-backed shared state and auxiliary data · `backend/storage/src/redis`

### Tracker

BitTorrent announce service

- [Tracker](https://github.com/arcadia-solutions/arcadia/blob/main/tracker/arcadia_tracker/src/main.rs): announce service · BitTorrent announce service entrypoint · `tracker/arcadia_tracker/src/main.rs`
- [Tracker Routes](https://github.com/arcadia-solutions/arcadia/blob/main/tracker/arcadia_tracker/src/routes.rs): router · Tracker route wiring and HTTP surface · `tracker/arcadia_tracker/src/routes.rs`
- [Announce Handler](https://github.com/arcadia-solutions/arcadia/blob/main/tracker/arcadia_tracker/src/announce/handlers/announce/handle_announce.rs): peer updates · Handles announce traffic and peer state updates · `tracker/arcadia_tracker/src/announce/handlers/announce/handle_announce.rs`
- [Tracker Services](https://github.com/arcadia-solutions/arcadia/tree/main/tracker/arcadia_tracker/src/services): announce logic · Announce service coordination and tracker-side business rules · `tracker/arcadia_tracker/src/services`

### Background Jobs

Scheduled maintenance and reconciliation tasks

- [Scheduler](https://github.com/arcadia-solutions/arcadia/blob/main/backend/periodic-tasks/src/periodic_tasks/scheduler.rs): job runner · Periodic-tasks scheduling and dispatch · `backend/periodic-tasks/src/periodic_tasks/scheduler.rs`
- [Periodic Tasks](https://github.com/arcadia-solutions/arcadia/tree/main/backend/periodic-tasks/src/periodic_tasks): maintenance jobs · Scheduled reconciliation jobs for points, warnings, users, peers, torrents, badges, and classes · `backend/periodic-tasks/src/periodic_tasks`

### Infrastructure

Shared runtime dependencies and external systems

- **Relational DB**: primary datastore · SQL database accessed through SQLx migrations and offline query metadata
- **Redis**: shared cache · Shared cache/queue used by backend services
- [External Systems](https://github.com/arcadia-solutions/arcadia/tree/main/kiwiirc): integrations · Email, IRC, image hosting/processing, metadata sources, and embedded IRC chat · `kiwiirc`

### Shared Lib

Compile-time shared Rust primitives

- [Shared Primitives](https://github.com/arcadia-solutions/arcadia/tree/main/shared/src/tracker): shared crate · Common tracker/domain models, telemetry, and error helpers · `shared/src/tracker`

## Connections

- Vue SPA → API Client: uses · SPA calls the generated site API client
- Vue SPA → API Server: HTTP · Browser traffic reaches the web API
- API Server → Routes: wires · Server mounts the route tree
- Routes → Handlers: dispatches · Routes are implemented by domain handlers
- Handlers → Auth Middleware: protected by · Endpoints rely on authentication and permission enforcement
- Handlers → API Services: calls · Handlers invoke side-effect and integration services
- Handlers → Repositories: reads/writes · Handlers persist and query site data through repositories
- API Services → Store Services: delegates · Service logic reuses storage-side domain services
- Repositories → Models: maps · Repositories operate on typed data models
- Repositories → Relational DB: SQLx · Repository queries execute against the relational database
- Store Services → Relational DB: queries · Domain services also persist to the database
- API Services → Redis: uses · API integrates with shared Redis state
- Redis → Redis: backs · Storage redis module targets the Redis infrastructure
- Tracker → Tracker Routes: wires · Tracker server mounts routes and middleware
- Tracker Routes → Announce Handler: dispatches · Announce traffic is handled by announce endpoints
- Announce Handler → Tracker Services: calls · Announce handling delegates to tracker service logic
- Tracker Services → Relational DB: updates · Tracker state is persisted in the database
- Tracker → Shared Primitives: imports · Tracker compiles against shared primitives
- API Server → Shared Primitives: imports · API compiles against shared primitives
- Scheduler → Periodic Tasks: runs · Scheduler triggers the periodic task modules
- Periodic Tasks → Relational DB: reconciles · Background jobs recompute and maintain database state
- Periodic Tasks → Redis: touches · Some maintenance flows interact with Redis
- API Services → External Systems: calls out · API emits email, IRC, image, and metadata integrations
- Vue SPA → External Systems: embedded chat · Frontend includes IRC chat integration via KiwiIRC
