Merge pull request #384 from lklynet/feature/docs-refresh

Refresh docs navigation and add user guide

Author: lklynet

DEVELOPMENT.md

@@ -0,0 +1,140 @@
+# Development
+
+This file is for contributors and maintainers working on Aurral locally. For normal installation and first-run setup, use [README.md](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:
+
+```bash
+npm install
+```
+
+## Local App
+
+Run backend and frontend together:
+
+```bash
+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:
+
+```bash
+npm run dev:backend
+```
+
+Run only the frontend:
+
+```bash
+npm run dev:frontend
+```
+
+Build the frontend:
+
+```bash
+npm run build
+```
+
+Start the production server after building:
+
+```bash
+npm start
+```
+
+## Checks
+
+Run tests:
+
+```bash
+npm test
+```
+
+Run frontend lint:
+
+```bash
+npm run lint --workspace frontend
+```
+
+Build a local Docker image:
+
+```bash
+npm run docker:build
+```
+
+Run a local Docker image:
+
+```bash
+npm run docker:run
+```
+
+## Repository Layout
+
+```text
+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