livef12rocks/CLEANUP_PLAN.md

Cleanup Plan — live.f12.rocks

Phase 0 analysis (2026-07-18). Working branch: cleanup/code-quality.

Project snapshot

Area	Detail
Stack	Python 3.11 (Docker), FastAPI, gmic, rembg, Docker Compose
Size	~7 Python modules under app/, ~1.3k LOC
Tests	None (pre-cleanup)
Lint/format	None (pre-cleanup)
CI	None
Lockfile	Soft pins in requirements.txt only

Findings (prioritized)

1. No test/CI/lint baseline — high risk for refactors
2. pipeline.py god module (642 LOC) — medium risk; defer split until tests exist
3. Meta JSON race (worker + web concurrent writes) — documented, not fixed (behavior change)
4. Dead code: blend_layers() unused
5. Duplication: atomic JSON write ×3, basicConfig ×2, bool-env parsing ×2, compose env block ×2
6. Double meta read on index page (read_status + read_manifest)
7. compare-bg/ — removed (was a standalone experiment)
8. make_random.py — external reference only, document in ARCHITECTURE

Risk matrix

Area	Risk	Action
Formatter/linter setup	Low	Phase 1
Dead code removal	Low	Phase 1
.gitignore / .python-version	Low	Phase 1
Extract io_utils, env_utils	Low	Phase 2
Compose env DRY (YAML anchor)	Low	Phase 2
Meta read dedup in main.py	Low	Phase 3
Magic numbers → config constants	Low	Phase 3
Characterization tests	Low	Phase 5 (before deeper refactors)
pipeline.py split	Medium	Deferred — tests first, split later
Meta file locking	Medium–High	Deferred — behavior change
Dependency major bumps	Medium	List only, no auto-bump

Roadmap & commits

Phase	Step	Commit theme
0	This file	docs: add cleanup plan from phase-0 analysis
1	pyproject.toml + ruff	chore: add pyproject.toml with ruff and pytest config
1	ruff format	style: apply ruff format to Python sources
1	dead code + gitignore	chore: remove dead code and extend gitignore
2	io_utils extraction	refactor: extract atomic JSON helpers to io_utils
2	env_utils + logging	refactor: share env-bool parsing and logging setup
2	compose DRY	chore: deduplicate compose environment blocks
3	config constants	refactor: replace magic numbers with named constants
3	meta read dedup	refactor: read job meta once in list_jobs
4	dev requirements	chore: add dev requirements and python version pin
4	Gitea CI	ci: add lint and test workflow
5	tests	test: add characterization tests for core modules
5	docs	docs: update README and add ARCHITECTURE

Conscious non-goals

• No pipeline.py module split in this pass
• No meta file locking / concurrency fix
• No dependency major version bumps
• No changes to compare-bg/ experiment (later removed entirely)
• No deploy CI (manual docker compose on boka stays)
• No behavior changes to gmic/rembg processing logic