livef12rocks/CLEANUP_REPORT.md

Cleanup Report — live.f12.rocks

Branch: cleanup/code-quality (local only, not pushed).
Completed: 2026-07-18.

Summary

Incremental code-quality cleanup across 10 commits. No intentional behavior changes to the photo pipeline, worker loop, or web UX.

What changed

Step	What	Why	Risk	Verification
Phase 0	CLEANUP_PLAN.md	Analysis + roadmap	Low	—
Tooling	pyproject.toml, requirements-dev.txt, .python-version	Ruff + pytest baseline, pin 3.11	Low	ruff check, pytest
Style	Ruff format entire app/	Consistent style	Low	ruff format --check
Dead code	Removed unused blend_layers()	Less noise	Low	grep + pytest
.gitignore	Build/coverage/venv patterns	Keep repo clean	Low	—
io_utils	Atomic JSON helpers	DRY meta/processed I/O	Low	test_io_utils, pipeline/worker tests
env_utils / logging_config	Shared bool env + logging	DRY	Low	test_env_utils, pytest
compose.yml	YAML anchor for env	DRY, fewer drift bugs	Low	docker compose config (manual)
Config	PREPROCESS_TIMEOUT constant	Named magic number	Low	default still 120s
read_meta()	Public meta accessor; list_jobs reads once	Perf + clarity	Low	test_pipeline, test_main
Tests	33 characterization tests	Safe refactor baseline	Low	pytest -q
CI	.gitea/workflows/ci.yml	Lint + test on push/PR	Low	workflow syntax
Docs	README.md, ARCHITECTURE.md	Onboarding	Low	—

What was NOT changed (and why)

Item	Reason
pipeline.py module split	Medium risk without broader integration tests; deferred
Meta file locking	Behavior change; documented in ARCHITECTURE.md
Dependency major bumps	Per plan — list only, no auto-bump
compare-bg/	Separate experiment; left untouched
Deploy CI	Manual deploy on boka stays; STANDARDS says ask first
FastAPI TemplateResponse API migration	Deprecation warning only; no functional change
_validate_job_id always sanitizes to valid ID	Pre-existing; documented in tests

Bugs noticed (not fixed)

1. Meta JSON race — worker and web concurrent RMW without locking.
2. _filter_timeout_override global — thread-unsafe under concurrent remix (uvicorn workers).
3. sanitize_stem("a/b") → "b" — Path.stem drops path prefix before slash replacement.
4. _validate_job_id — sanitization makes rejection path effectively unreachable.

Dependency notes (suggestions only)

Package	Current pin	Note
fastapi	<0.117	0.117+ available; test before bump
onnxruntime	<1.20	Very old pin; rembg may allow newer in future
pillow	<11	Pillow 11 exists; verify rembg compatibility

No lockfile added — soft pins kept to avoid changing Docker resolve behavior.

How to verify locally

git checkout cleanup/code-quality
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
ruff check app/ tests/
pytest -q
# Full stack:
cp .env.example .env   # set DATA_HOST_DIR=./data
docker compose up --build

Commits on branch

docs: add cleanup plan from phase-0 analysis
chore: add pyproject.toml with ruff and pytest config
style: apply ruff format and extend gitignore
refactor: extract atomic JSON helpers to io_utils
refactor: share env-bool parsing and logging setup
chore: deduplicate compose environment blocks
refactor: named preprocess timeout and single meta read
test: add characterization tests for core modules  (+ CI workflow)
docs: update README and add ARCHITECTURE

External references

• compare-bg/ — local venv .venv-compare/ and 1.5GB model cache (gitignored)
• make_random.py — external reference script, not vendored
• Submodule/symlink: none