Instructions for AI agents (and humans) working in this repository.
BookFlow is a small self-hosted OPDS server: read-only filesystem → SQLite index → OPDS catalogs, plus on-demand X3/X4 EPUB optimization and multi-user reading progression. The plan is complete (milestones M1–M8 + optional items); expect maintenance, bug fixes, and small features rather than greenfield work.
- How it fits together: ARCHITECTURE.md (start here)
- How to run it: README.md
- Config, endpoints, dev/prod details: REFERENCE.md
uv sync # install deps
uv run ruff check . # lint (gate before every commit)
uv run pytest -q # full suite: 366 tests
uv run pytest -q tests/test_opds.py # single file (seconds)
uv run flask --app bookflow.app run --port 8000 # dev server (flask defaults to :5000)
uv run alembic upgrade head # apply migrations
uv run alembic revision --autogenerate -m "..."
uv run gunicorn --bind 0.0.0.0:8000 bookflow.wsgi:app
docker compose up -d --build # containerized run (Dockerfile)
# prebuilt image: docker pull ghcr.io/syfq91/bookflow:latest && docker compose up -d
# publish image: Actions → "Publish Docker image to GHCR" (manual, workflow_dispatch)Verify before committing: uv run ruff check . && uv run pytest -q.
Both must pass. Do not commit unless explicitly asked.
Tests cover behavior; for end-to-end checks run a detached instance on a scratch data dir:
export OPDS_DATA_DIR=/tmp/bf-smoke OPDS_ADMIN_PASSWORD=smokepass \
OPDS_DATABASE_URL="sqlite+pysqlite:////tmp/bf-smoke/live.db"
setsid nohup uv run flask --app bookflow.app run --host 127.0.0.1 --port 8767 \
> /tmp/bf-smoke.log 2>&1 < /dev/null &
# kill later with the regex-bracket trick (plain pkill kills your own shell line):
pkill -f "[f]lask --app bookflow.app run"uv run alembic upgrade headfirst if the scratch DB is new.- Login for admin pages: scrape
csrf_tokenwithgrep -o 'name="csrf_token" value="[^"]*"' | head -1(it appears twice per page — forms + meta), then POST/admin/loginwith a cookie jar. - OPDS uses Basic auth:
-u admin:<password>.
- Toolchain: Python ≥3.14, uv, Flask 3, SQLAlchemy 2, Alembic, SQLite.
Ruff rules
E,F,I,UP,B,C4,SIM,RUF059(ARGdeliberately off — seepyproject.toml), line length 88,target-version = "py314". - Style:
from __future__ import annotationsat the top of every module; type-hint public functions; docstrings on modules/classes/public functions; inline comments are rare — prefer clear code over narration. - Config: a frozen
Settingsdataclass (config.py); never reados.environoutside it. Everything is reachable ascurrent_app.config["SETTINGS"]. - Database: open sessions only via
session_scope()(commit/rollback/ close handled). SQLAlchemy 2 style:Mapped[...]/mapped_column,select()— no legacyQuery. Keep sessions short; never hold one across I/O or renders. - Web: blueprints only (auth, admin, opds, progression); register new
ones in
create_app. OPDS errors must be blueprint-scoped (@bp.errorhandler) so admin pages keep HTML error pages — the single app-levelHTTPExceptionhandler increate_appexists only for routing failures (a failed URL match has no blueprint to dispatch to) and must return every other request unchanged. Every state-changing admin route is automatically CSRF-checked by the blueprint'sbefore_request— views just read the form. - Templates: server-rendered Jinja extending
layout.html; CSRF token via the globalcsrf_token(); existing badge/detail/grid CSS classes instatic/style.css(addbadge-warn-style variants there if needed). - Tests: mirror existing files. Fixture chain is
settings(conftest, temp dir + DB) →build_app(settings)(conftest factory: runsalembic upgrade headunlessmigrate=False, resets the engine around each test) → per-suiteapp→client. A suite that needs another password,browse_root, or an unmigrated app defines its own*_settings/appfixture on top ofbuild_app. Reusetests/factories.py(make_epub,make_pdf,csrf_token,login_admin,insert_books,alembic_config, feed-parsing helpers) instead of hand-rolling files; seed rows withinsert_books(...)when no real file is needed.
- The library is read-only. No code may write, rename, or delete
anything under a registered folder. All writes go to SQLite and
data/cache/. - Optimization is on-demand only. epubkit and cbz2xtc run exclusively
inside
optimize_book(), reached only from/opdsx3|/opdsx4/download/<id>. Never call them from scanning, startup, routes, or background tasks. - Paths come from the DB, not the URL.
book_file()inlibrary/paths.pyis the single source of book paths and enforces root containment viaresolve()+is_relative_to. Don't construct filesystem paths from user input anywhere else. - Cache is disposable, index must agree. Cache files live at
data/cache/optimized/{x3,x4}/<book_id>.{epub,xtc}, written through.tmp/<uuid>.<ext>+Path.replace(), and validated against theoptimized_booksrow (source_mtime,source_size,optimized_size). Writes to file and row happen together; readers treat any mismatch as a miss. - Progression is per (user, book), one row per user per book,
shared across original and X3/X4 downloads. Timestamps: accept naive as
UTC, serialize with
Zand microsecond precision (replays must compare equal). - User credentials stored in DB. Argon2id in SQLite, session auth for
/admin(admins only), HTTP Basic for/opds(all users), OPDS 401 body is the Authentication Document. Never log passwords, cookies, or auth headers. - Vendored epubkit & cbz2xtc are third-party code (
optimizer/epubkit/andoptimizer/cbz2xtc/, MIT — keepNOTICE, keep the ruff per-file-ignores). Avoid editing them; upstream them separately if the pipelines themselves must change. - Non-goals: no uploads, book delete/rename/move or metadata/cover editing, cloud storage, Calibre/Elasticsearch/Redis/Celery/K8s/ microservices, a separate epubkit HTTP server, background or scheduled optimization, pre-generated X3/X4 files, and no separate progression per device or per optimization profile. Keep the application small.
optimizer/epubkit/(package) shadows nothing now — do not recreate a siblingoptimizer/epubkit.py; Python would silently prefer the package.- An app is built only through
create_app()(build_appin tests,bookflow.wsgiin production) — never at import time, so no test can write into the repo by importing the package. Don't build one outside the fixture chain: its engine would leak (that's whatreset_engine()is for). - OPDS feeds paginate at 50; device feeds (
/opdsx3,/opdsx4) list the whole library with EPUB acquisitions rewritten per profile and other formats falling back to/opds/download/<id>— keep that fallback when adding formats. - Search uses SQL
ilikewith escaped% _ \— reuse the existing escaping helper if you touch queries. - Flask's default error pages are intentional for
/admin; only the OPDS and progression blueprints render structured errors. - The session secret is auto-generated and persisted to
data/.session_secretwhenOPDS_SESSION_SECRETis unset (seeresolve_session_secret()); the old shared dev literal no longer exists. Never log the file's contents. - The only background job is the rescan thread (
bookflow/auto_scan.py): one daemon thread per process whenOPDS_AUTO_SCAN_INTERVAL > 0(default3600,0/offdisables), which just callsscan_folder()for every folder and thenprune_orphaned_cache()— never epubkit or cbz2xtc. A cycle takes a non-blockingflockondata/.auto_scan.lock, so gunicorn workers do not scan twice. The sharedsettingsfixture sets the interval to0, so no test app spawns a thread; suites that want one (tests/test_auto_scan.py) build anauto_appand must stop the scanner in teardown, or it outlives the test and racesreset_engine().
- Direct commits to
main, pushed togithub.com:syfq91/bookflow. - Message style: short imperative summary, optionally scoped
(
Milestone 6: epubkit integration,Add gunicorn dependency and .env.example). - Stage only intended files; run the verify command above first; never commit secrets (test passwords in fixtures are fine — they aren't real).