wrongmove/docs/plans/2026-02-21-build-optimization-design.md

# Build Optimization Design

## Goal

Minimize Docker build times and production image sizes for both the backend (Python/FastAPI) and frontend (React/Vite) builds.

## Changes

### 1. Dependency Cleanup

#### Backend: Remove from pyproject.toml

| Package | Reason | Replacement |
|---------|--------|-------------|
| `watchdog` | Zero production imports | None |
| `tqdm` | Progress bars in 4 files | `logging.info()` |
| `pandas` | CSV export only (1 file) | `csv.DictWriter` |
| `apprise` | Notifications (1 file) | Remove |
| `opencv-python` | Includes GUI libs (~40MB) | `opencv-python-headless` |

#### Backend: Fix missing prod dep

- Add `httpx` to production dependencies (imported in `api/auth.py` but currently dev-only).

#### Frontend: Remove from package.json

| Package | Reason |
|---------|--------|
| `@tabler/icons-react` | Zero imports, replaced by `lucide-react` |
| `crossfilter2` | Zero imports |
| `date-fns` | Zero imports, replaced by `chrono-node` |

#### Frontend: Move to devDependencies

- `@types/crossfilter`, `@types/d3`, `@types/mapbox-gl`, `@types/turf`

### 2. Backend Dockerfile

- Add `# syntax=docker/dockerfile:1` for BuildKit support.
- Replace `pip` with `uv` (10-25x faster). Copy binary from `ghcr.io/astral-sh/uv:latest`.
- Add BuildKit cache mounts for `/var/cache/apt`, `/var/lib/apt/lists`, `/root/.cache/uv`.
- Remove `--no-cache-dir` from pip install (cache mount handles this).
- Remove `libgl1` from runtime-base (`opencv-python-headless` doesn't need it).
- Add non-root `appuser` in the final stage.
- Add `HEALTHCHECK` using curl to `/health`.

### 3. Frontend Dockerfile

- Add `# syntax=docker/dockerfile:1` for BuildKit support.
- Add npm cache mount (`/root/.npm`) for `npm ci`.
- Add non-root nginx user.
- Add `HEALTHCHECK`.

### 4. CI Pipeline (Woodpecker)

- Enable BuildKit in the API pipeline (`DOCKER_BUILDKIT=1` in `plugins/docker` settings).
- Frontend pipeline (Kaniko) already has good caching; no changes needed.

### 5. Source Code Changes

#### tqdm removal

Replace `tqdm` progress bars with `logging.info` in:
- `services/image_fetcher.py`
- `services/floorplan_detector.py`
- `services/route_calculator.py`
- `repositories/listing_repository.py`

#### pandas removal

Rewrite CSV export in the file that imports pandas to use `csv.DictWriter`.

#### apprise removal

Remove `notifications.py` or its apprise-dependent code.

#### requirements.txt regeneration

After updating `pyproject.toml`, regenerate with `poetry export --without-hashes -f requirements.txt -o requirements.txt` (or with hashes if preferred).

## Expected Impact

- **Image size**: ~50-80MB reduction (headless OpenCV, removed deps).
- **Local rebuild speed**: 2-5x faster on cache hits (BuildKit mounts + uv).
- **CI rebuild speed**: Moderate improvement from BuildKit layer caching; cache mounts are ephemeral in CI but layer caching already works.
- **Security**: Non-root user in both production images.