spotiarr-architecture

What problem does it solve?

Spotiarr contributors need a reliable rulebook for deciding where new code belongs (backend, frontend, or shared) so the codebase stays consistent, testable, and maintainable.

Core Features & Use Cases

• Backend DDD-lite layering: Enforces a direction of dependencies so presentation → application → domain, with infrastructure implementing contracts only.
• Frontend state and real-time boundaries: Uses TanStack Query for server state, Zustand slices for client state, and a dedicated useServerEvents hook for SSE sync.
• External integration safety: Requires all Spotify HTTP calls to go through CircuitBreaker.execute() in infrastructure/external/circuit-breaker.ts to prevent unsafe direct calls and to preserve circuit state across restarts.
• Repository placement guidance: Clarifies where use-cases/services register (apps/backend/src/container.ts) and where shared types/utilities live (packages/shared/).

Quick Start

Ask: “Given this Spotiarr feature request and the files it will touch, where should the new backend and frontend code be placed according to the spotiarr architecture rules?”