mirror of
https://github.com/calibrain/shelfmark.git
synced 2026-10-02 13:35:47 +01:00
463ef49ac3
## Why `BOOK_LANGUAGE` is a per-reader property, not a per-instance one. On a shared install one household member searches in German while another wants English and German — today whoever changes the setting changes it for everyone, and the only escape is re-picking languages in the filter on every single search. The per-user override machinery already carries `SEARCH_MODE`, the metadata providers and the default release sources, so the language default mostly had to opt into it. ## What changed **The field.** `BOOK_LANGUAGE` becomes `user_overridable` and moves from the **General** tab to **Search Mode**, next to the other user-overridable search defaults (per [review](https://github.com/calibrain/shelfmark/pull/1255#issuecomment-5391189094) — the first version had the Search section span two tabs, this one doesn't). Admins set it per user in the user editor, users set it in **My Account → Search Preferences**, and the Search Mode tab carries the usual "N users override this" summary. **No migration for the move.** `general` and `search_mode` both persist into `settings.json`, and a field's value is resolved through `load_config_file(tab)` for the tab it's declared on — so an install that already stores `BOOK_LANGUAGE` keeps its value. Checked against a `settings.json` written while the field still lived on General: the stored value resolves unchanged, a fresh install still gets `["en"]`, and `BOOK_LANGUAGE` in the environment still overrides both. **The two places the default is read.** - `/api/config` seeds the frontend's language filter, so it now resolves `BOOK_LANGUAGE` for the session user. - `build_release_search_plan` falls back to the default whenever a request carries no language filter — which is exactly what the filter's "Default" option sends. It takes an optional `user_id`, passed by `/api/releases` from the session and by the Prowlarr retry path from `task.user_id`, so a retry re-searches in the languages of whoever queued the download. **Validation.** Overrides go through `normalize_language()`, so `"German"`, `"ger"` and `"de"` all store as `de`, and an unknown language is rejected with a message naming it instead of being silently searched for. An empty list stays an empty list (a deliberate "no default filter"), `null` clears the override as everywhere else, and ENV still wins: with `BOOK_LANGUAGE` set in the environment the field reports `fromEnv` and overrides are ignored. **Scope.** Only the language default becomes overridable. The two format lists left behind under "Default Search Filters" stay admin-only — they describe what the library and its post-processing accept, not what a reader wants to read. There's a test pinning that. ## Verification - 2681 unit tests pass (2670 before, 11 added) - `ruff check`, `ruff format`, `basedpyright` over backend and tests, and `vulture` all clean; frontend lint, format, typecheck and 126 unit tests clean - `docs/environment-variables.md` regenerated via `scripts/generate_env_docs.py` (the `BOOK_LANGUAGE` row follows the field into the Search Mode section) - Manually against a two-user instance with builtin auth (first round, before the tab move): with user A on German and user B on English+German, `/api/config` returns each reader their own `default_language` and an unfiltered `/api/releases` plans the matching languages; an admin can set and read the same override for another user; clearing it falls back to the global value; a stray `"klingon"` is rejected; and `BOOK_LANGUAGE` in the environment overrides both users with the field marked `fromEnv` - After the tab move I re-ran the suites above plus the stored-value/fresh-install/ENV check described under "No migration for the move"; the behaviour it exercises is what the move could have broken Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: CaliBrain <calibrain@l4n.xyz>
Source Code Documentation
This directory contains the frontend application for Calibre-Web Automated Book Downloader.
Structure
src/
└── frontend/ # React + TypeScript frontend application
├── public/ # Static assets (logo, favicon)
├── src/ # Source code
│ ├── components/ # React components
│ ├── App.tsx # Main application component
│ └── styles.css # Global styles
├── package.json # Dependencies and scripts
├── vite.config.ts # Vite configuration
└── tsconfig.json # TypeScript configuration
Frontend Development
Prerequisites
- Node.js (v16 or higher)
- npm or yarn
Quick Start
From the project root:
# Install dependencies
make install
# Start development server (http://localhost:5173)
make dev
# Build for production
make build
# Preview production build
make preview
# Run type checking
make frontend-typecheck
Alternatively, from src/frontend:
npm install
npm run dev
npm run build
Technology Stack
- Framework: React 18 with TypeScript
- Build Tool: Vite 5
- Styling: TailwindCSS 3
- Communication: WebSocket for real-time updates
Key Features
- Search Interface: Real-time book search with filtering
- Download Queue: Live status updates via WebSocket
- Details Modal: Rich book information display
- Responsive Design: Mobile-first approach
Development Tips
Hot Module Replacement (HMR)
The development server supports HMR for instant feedback during development.
API Integration
The frontend communicates with the Flask backend via:
- REST API endpoints (
/api/*) - WebSocket connection (
ws://localhost:8084/ws)
Building for Production
The production build is optimized and minified:
make build
Output is generated in src/frontend/dist/
Type Safety
Run TypeScript checks without building:
make frontend-typecheck
Debugging
Development Server Issues
- Ensure port 5173 is available
- Check that the backend is running on port 8084
- Verify WebSocket connection in browser console
Build Issues
- Clear
node_modulesand reinstall:make clean && make install - Check Node.js version compatibility
- Verify TypeScript configuration