CLEANUP_PLAN.md

@@ -0,0 +1,68 @@
+# 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/`** — separate experiment, leave as-is (gitignored cache)
+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
+- No deploy CI (manual `docker compose` on boka stays)
+- No behavior changes to gmic/rembg processing logic