parking_solution/wiki/decisions/vision-service-packaging.md

type, tags, sources, updated, status

type	tags	sources	updated	status
decision	parking decisions vision anpr monorepo packaging		2026-06-19	settled

Decision: the vision service lives in this monorepo (apps/vision/), wired into Turbo via a shim

Taken 2026-06-19, when planning how to implement the host-side [[opencv-anpr-service|vision service]] decided in vision-service. That decision settled WHAT (a separate localhost Python process) and the recognizer baseline (opencv-anpr-service); this one settles WHERE the source lives and how it joins the build.

Decision

1. In THIS monorepo, at apps/vision/ — a Python/FastAPI service co-located with the Node backend, not a separate repository. One git history, atomic cross-cutting commits (the /analyze contract + the Node-side adapter change together), one wiki.
2. Still a separate OS process — co-location is source-level only. It runs as its own process (uvicorn), called over localhost HTTP by the Node backend, with its own failure domain. Nothing about putting it in apps/vision/ weakens the runtime isolation vision-service requires.
3. Wired into the Turbo task graph via a thin package.json shim. pnpm-workspace.yaml already globs apps/*, so an apps/vision/package.json auto-joins the workspace. Its scripts shell out to Python tooling, so the existing turbo run tasks cover it:
   • dev → uv run uvicorn app:app --reload (matches turbo.json dev: persistent, uncached)
   • lint → ruff check · test → pytest · typecheck → ruff/mypy
   • build → no-op or model-fetch (Python has no dist/**; the build task's outputs: ["dist/**"] simply won't match — fine). If models are fetched/cached at build, point outputs at the model dir. Python dependencies stay managed by uv + pyproject.toml (NOT pnpm) — the shim only exposes tasks, not deps.
4. Node talks to it through an interface (VisionClient behind a port, the device-adapter-pattern style) so the recognizer/service is swappable without touching business logic — as opencv-anpr-service already specifies.

Why co-located beats a separate repo

• Atomic changes. The service contract (POST /analyze shape) and its Node consumer evolve together; one repo = one PR, no two-repo version skew.
• uv makes Python-in-monorepo painless — fast, lockfile-based, offline-friendly (fits offline-first); the appliance build pulls a pinned env.
• Turbo still orchestrates it. The shim makes turbo run lint/test include the Python service as a first-class node — one command lints front, back, AND vision — even though Turbo can't build Python. Turbo orchestrates tasks, and a task can be a Python command.
• One knowledge base. The wiki + CLAUDE.md already describe the whole system; a split repo fragments that.

Why this still honors the isolation decision

The "vision-service" decision is about runtime isolation (own process + failure domain) and license isolation (AGPL obligations don't reach the Node/React code because it is not linked — it's a separate program over HTTP). Neither depends on a separate repository. AGPL's reach is a linking/distribution-boundary question between programs, not a which-folder question. A Python service in apps/vision/ that Node calls over localhost is exactly as isolated, license-wise, as one in its own repo.

• With the opencv-anpr-service MIT-end-to-end baseline, the AGPL pressure to split the repo out largely evaporates (pending the weight-provenance caveat). Co-location is the low-friction default.
• If a true-AGPL model (Ultralytics YOLO) is later adopted, its weights live under apps/vision/ — still fine (separate process), and that dir is the natural place to document the license boundary + the [[standing-decisions|scoped exception]].

Rejected

• Separate repo — strongest separation, but loses atomic contract changes and adds coordination overhead; justified only if a different team owns it or the AGPL concern becomes acute. Kept as the fallback if either happens.
• Embed Python in the Node process (opencv4nodejs / a child-process module) — already rejected by vision-service (native-build pain, no process isolation, shares the app's failure + license surface). Unchanged.
• A Python package under packages/ — packages/ is for shared JS libraries imported by other workspaces; the vision service is a deployable app, so apps/vision/ is the right bucket.

Consequences

• Add apps/vision/ (pyproject.toml + uv.lock, FastAPI app.py, a thin package.json shim); apps/* glob picks it up. Update the repo-layout block in the root CLAUDE.md + this wiki.
• A Dockerfile/process unit builds the Python service as its own image/process for the appliance; CI runs ruff/pytest (via the shim or a dedicated job).
• The Node backend gains a VisionClient adapter (localhost HTTP) + per-camera opt-in wiring (the open item in opencv-anpr-service).
• Not built yet — this is the packaging decision; scaffolding follows when the vision work starts (the "scaffold as the work reaches them" rule in CLAUDE.md).

Open

• uv vs. pip-tools/poetry for the Python env (leaning uv — speed + lockfile + offline).
• Whether build should fetch/cache model weights (and set Turbo outputs to the model dir) or keep weights out of the build entirely (baked into the Docker image instead).
• Container/runtime supervision on the appliance (systemd unit vs. compose) — deployment detail, defer to the install/hardening pass.