Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
140 lines (103 loc) · 3.61 KB

DEVELOPMENT.md

File metadata and controls

140 lines (103 loc) · 3.61 KB
Raw

Development

This file is for contributors and maintainers working on Aurral locally. For normal installation and first-run setup, use README.md.

Requirements

  • Node.js compatible with the repo dependencies. The Docker image uses Node 26 Alpine.
  • npm
  • A reachable Lidarr instance for integration-heavy workflows

Install dependencies:

npm install

Local App

Run backend and frontend together:

npm run dev

This starts:

  • Backend: http://localhost:3001
  • Frontend dev server: http://localhost:3000

The frontend proxies /api and /ws to the backend.

Run only the backend:

npm run dev:backend

Run only the frontend:

npm run dev:frontend

Build the frontend:

npm run build

Start the production server after building:

npm start

Checks

Run tests:

npm test

Run frontend lint:

npm run lint --workspace frontend

Build a local Docker image:

npm run docker:build

Run a local Docker image:

npm run docker:run

Repository Layout

backend/
  config/              SQLite, settings, encryption, sessions, constants
  middleware/          auth, permissions, cache, validation, URL validation
  routes/              API route groups
  services/            Lidarr, discovery, metadata, images, flows, Soulseek, Navidrome
  scripts/             maintenance scripts
frontend/
  src/
    components/        shared UI components
    contexts/          auth, theme, toast
    hooks/             websocket, volume, page hooks
    pages/             Discover, Library, Flow, Settings, Requests, etc.
    utils/             API client and helpers
lib/                   version resolution helpers
scripts/               release helper scripts
.tests/                node:test suites
web/                   static public helper pages

Architecture Notes

Aurral is a single deployable web app:

  • Express serves /api/*, WebSockets, stream endpoints, and the built React frontend.
  • React/Vite provides the app UI and PWA support.
  • SQLite stores durable state.
  • Lidarr remains the source of truth for the main music library.
  • Aurral-generated flow files are kept in a separate downloads/output tree.
  • WebSocket channels push discovery updates, download statuses, and flow status changes to connected clients.

Main backend route groups:

Route prefix Purpose
/api/health Liveness, bootstrap, app version, auth state, integration status, WebSocket stats.
/api/onboarding First-run setup before onboarding is complete.
/api/auth Login, logout, and current user.
/api/users User management, account settings, listening history, Lidarr defaults, discover layout.
/api/settings Admin settings, logs, Lidarr profile/tag lookups, connection tests, notifications.
/api/search Catalog and artist search.
/api/artists Artist details, images, similar artists, previews, release groups, overrides.
/api/library Lidarr library artists, albums, tracks, stream, lookup, downloads, refresh, delete.
/api/discover Recommendations, refresh, tags, blocklist, preferences, feedback, nearby shows.
/api/requests Normalized Lidarr queue/history request tracking.
/api/weekly-flow Flows, imported playlists, jobs, worker settings, downloads, status, artwork.
/api/image-proxy Cached/proxied external images.

Periodic backend work includes:

  • Due flow refreshes
  • Pending flow worker jobs
  • Incomplete imported playlist retries
  • Expired sessions
  • Stale discovery cache refreshes
  • Download status broadcasts
  • Flow status broadcasts