---
type: decision
tags: [parking, decisions, vision, anpr, monorepo, packaging]
sources: []
updated: 2026-06-19
status: 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|fast-alpr]]); 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|separate process]]" 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|fast-alpr]] 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.