Initial computer vision kit

Author: Boyeep

.github/workflows/template-ci.yml

@@ -0,0 +1,46 @@
+name: Template CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          cache-dependency-path: |
+            package-lock.json
+            frontend/package-lock.json
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install root tooling
+        run: npm ci
+
+      - name: Install frontend dependencies
+        run: npm ci
+        working-directory: frontend
+
+      - name: Install backend dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ./backend[dev]
+
+      - name: Generate API types
+        run: npm run api:types
+
+      - name: Run template checks
+        run: npm run check

.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+npm-debug.log*
+
+frontend/node_modules/
+frontend/.next/
+frontend/out/
+frontend/tsconfig.tsbuildinfo
+frontend/.env.local
+frontend/AGENTS.md
+frontend/CLAUDE.md
+
+backend/.venv/
+backend/.pytest_cache/
+backend/__pycache__/
+backend/**/*.pyc
+backend/**/*.pyo
+backend/.env
+
+.DS_Store
+Thumbs.db
+
+__reference_nextjs_go_monorepo_kit/
+deep-research-report.md

.nvmrc

@@ -0,0 +1 @@
+22

README.md

@@ -0,0 +1,107 @@
+# nextjs-python-computer-vision-kit
+
+A full-stack starter monorepo for detection-first computer vision products built with Next.js and FastAPI.
+
+It combines a polished frontend, a Python API designed for image-processing workloads, shared root scripts, a documented OpenAPI contract, and a sample detection pipeline that runs on CPU with OpenCV so teams can start shipping product workflows before committing to a heavier model stack.
+
+## Stack
+
+- Next.js 16
+- React 19
+- TypeScript
+- Tailwind CSS 4
+- Python 3.12+
+- FastAPI
+- OpenCV
+- Docker Compose
+
+## Monorepo Structure
+
+- `frontend/`: Next.js app with a vision-console UI, API client helpers, and generated OpenAPI types
+- `backend/`: FastAPI service with health, pipeline catalog, and image-analysis routes
+- `docs/`: shared API contract
+- `scripts/`: root development and verification scripts
+- `.github/`: CI workflow for the template
+
+## Recommended Shape
+
+- architecture: inference-first
+- default demo: detection-first
+- optional frontend extension: webcam capture
+- later backend extension: segmentation
+- later workspace/package: training pipeline
+
+This keeps the template easy to understand while still leaving a clean path into more advanced CV workflows.
+
+## Why This Template Exists
+
+Most computer-vision starters are either model notebooks with no product layer or web templates with no real inference shape. This template sits in the middle:
+
+- product-minded frontend by default
+- backend structure ready for image upload, preprocessing, and model-serving extensions
+- typed API contract between the web app and the inference service
+- one-command local development from the repo root
+
+## Quick Start
+
+1. Install Node.js 22+ and Python 3.12+.
+2. Run `npm install` in the repo root.
+3. Run `npm install` in `frontend/`.
+4. Run `python -m pip install -e ./backend[dev]`.
+5. Run `npm run api:types`.
+6. Run `npm run dev`.
+
+Frontend: `http://localhost:3000`
+Backend: `http://127.0.0.1:8000`
+
+## Commands
+
+```bash
+npm run dev
+npm run dev:down
+npm run api:types
+npm run check
+```
+
+## API Contract
+
+- `docs/openapi.yaml` is the source of truth for the shared HTTP contract.
+- `frontend/src/generated/openapi.ts` is generated from that spec with `openapi-typescript`.
+- Run `npm run api:types` whenever backend payloads change.
+
+## Sample Pipelines Included
+
+- `starter-detection`: the default object-style detection sample used by the main frontend flow
+- `foreground-segmentation`: the first live extension pipeline, returning region polygons and derived boxes
+- `document-layout`: document-oriented box extraction for scanning and capture products
+- `dominant-color`: metrics-only extension pipeline for QA and analytics
+
+These are intentionally lightweight starter pipelines. They are there to prove the architecture and developer workflow, not to lock you into toy logic. Swap them for YOLO, ONNX Runtime, PyTorch, TensorRT, or a custom service when you are ready.
+
+## What You Get
+
+- reusable Next.js + Python computer-vision monorepo layout
+- upload-and-detect frontend starter UI
+- optional webcam capture mode that reuses the same inference contract
+- first segmentation extension pipeline using the same response boundary
+- FastAPI inference endpoint with typed response models
+- OpenCV-based sample processing that runs without a GPU
+- root scripts for local dev and checks
+- GitHub Actions workflow for frontend and backend verification
+- Docker Compose dev option
+
+## Notes
+
+- The backend in this starter is CPU-first on purpose so it is easier to clone, run, and extend.
+- The main story is intentionally detection-first so the template stays easy to explain and demo.
+- The current environment used to build this template did not have Python installed, so the frontend was verified locally but backend execution was prepared rather than run here.
+- If you move to heavier vision workloads, add a worker or model-service layer and keep the current API as the contract boundary.
+
+## Next Expansions
+
+- async job queue for long-running inference
+- persistent artifact storage
+- model registry and experiment tracking
+- richer segmentation overlays and mask visualizations
+- video ingestion pipelines
+- training or experiment workspace in a separate `ml/` or `training/` package

backend/.env.example

@@ -0,0 +1,7 @@
+APP_NAME=Next.js Python Computer Vision Kit API
+APP_ENV=development
+APP_HOST=127.0.0.1
+APP_PORT=8000
+CORS_ALLOWED_ORIGINS=http://127.0.0.1:3000,http://localhost:3000
+MAX_UPLOAD_SIZE_MB=8
+SAMPLE_MAX_DETECTIONS=8

backend/README.md

@@ -0,0 +1,30 @@
+# Backend
+
+The backend is a FastAPI service designed to be the stable contract layer for a detection-first computer-vision product.
+
+## Responsibilities
+
+- expose typed HTTP endpoints for health, pipeline discovery, and analysis
+- make the default sample workflow object detection with bounding boxes
+- expose segmentation as an extension through the same inference contract
+- validate uploads and normalize errors
+- keep model-specific logic behind a small service boundary
+- make it easy to swap sample OpenCV processors with heavier inference backends later
+
+## Install
+
+```bash
+python -m pip install -e .[dev]
+```
+
+## Run
+
+```bash
+python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+## Test
+
+```bash
+python -m pytest
+```

backend/app/__init__.py

@@ -0,0 +1 @@
+

backend/app/api/__init__.py

@@ -0,0 +1 @@
+

backend/app/api/routes/__init__.py

@@ -0,0 +1 @@
+

backend/app/api/routes/health.py

@@ -0,0 +1,16 @@
+from fastapi import APIRouter
+
+from app.config import get_settings
+from app.schemas import HealthResponse
+
+router = APIRouter()
+
+
+@router.get("/health", response_model=HealthResponse, tags=["health"])
+def health_check() -> HealthResponse:
+    settings = get_settings()
+    return HealthResponse(
+        status="ok",
+        app=settings.app_name,
+        environment=settings.app_env,
+    )