# 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