How arcadia-solutions/arcadia works
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: handlers Handlers · services API Services · frontend Vue SPA · main.rs API Server
Components 21
Frontend
Client-side Vue SPA and generated API client
- Vue SPA · Client-side rendered browser application
frontend - API 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 · Main backend web service entrypoint
backend/api/src/main.rs - Routes · HTTP route wiring and endpoint composition
backend/api/src/routes.rs - Handlers · Domain split request handlers for auth, torrents, users, forums, wiki, search, staff, and more
backend/api/src/handlers - API Services · Outbound services for auth, email, IRC, images, metadata, and announces
backend/api/src/services - Auth Middleware · Authentication and side-effect middleware enforcing permissions
backend/api/src/middlewares
Storage
SQLx-backed persistence boundary and Redis support
- Models · Typed relational models for site domains
backend/storage/src/models - Repositories · Domain repositories wrapping SQLx queries
backend/storage/src/repositories - Store Services · Storage-side shop, promotion, and bonus-point logic
backend/storage/src/services - Redis · Redis-backed shared state and auxiliary data
backend/storage/src/redis
Tracker
BitTorrent announce service
- Tracker · BitTorrent announce service entrypoint
tracker/arcadia_tracker/src/main.rs - Tracker Routes · Tracker route wiring and HTTP surface
tracker/arcadia_tracker/src/routes.rs - Announce Handler · Handles announce traffic and peer state updates
tracker/arcadia_tracker/src/announce/handlers/announce/handle_announce.rs - Tracker Services · Announce service coordination and tracker-side business rules
tracker/arcadia_tracker/src/services
Background Jobs
Scheduled maintenance and reconciliation tasks
- Scheduler · Periodic-tasks scheduling and dispatch
backend/periodic-tasks/src/periodic_tasks/scheduler.rs - Periodic Tasks · 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 · SQL database accessed through SQLx migrations and offline query metadata
- Redis · Shared cache/queue used by backend services
- External Systems · Email, IRC, image hosting/processing, metadata sources, and embedded IRC chat
kiwiirc
Shared Lib
Compile-time shared Rust primitives
- Shared Primitives · Common tracker/domain models, telemetry, and error helpers
shared/src/tracker
Connections 24
- 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