usda-vision/README.md

# USDA Vision

A unified monorepo combining the camera API service and the web dashboard for USDA vision experiments.

## Project Structure

- `camera-management-api/` - Python API service for camera management (USDA-Vision-Cameras)
- `management-dashboard-web-app/` - React web dashboard for experiment management (pecan_experiments)
- `supabase/` - Database configuration, migrations, and seed data (shared infrastructure)
- `media-api/` - Python service for video/thumbnail serving (port 8090)
- `video-remote/` - Frontend for video browsing (port 3001)
- `vision-system-remote/` - Camera/vision UI (port 3002)
- `scheduling-remote/` - Scheduling/availability UI (port 3003)
- `scripts/` - Host IP, RTSP checks, env helpers (see [scripts/README.md](scripts/README.md))
- `docs/` - Setup, Supabase, RTSP, design docs
- `mediamtx.yml` - RTSP/WebRTC config for MediaMTX streaming

## Quick Start

### Production Mode (Docker Compose)

**Recommended**: Use the `docker-compose.sh` wrapper script which automatically detects your host IP and sets all environment variables:

```bash
./docker-compose.sh up --build -d
```

The wrapper script automatically:
- Detects your host machine's IP address
- Sets all required environment variables (VITE_*, HOST_SITE_URL, etc.)
- Generates/updates the `.env` file
- Runs docker-compose with your arguments

**Alternative**: If you prefer to use `docker compose` directly, the `.env` file will be auto-generated on first run, or you can set environment variables manually.

For more details, see [Docker Compose Environment Setup](docs/DOCKER_COMPOSE_ENV_SETUP.md).

- Web: <http://localhost:8080>
- API: <http://localhost:8000>
- MQTT is optional; configure in API config if used (see `.env.example`).

To stop: `docker compose down`

### Development Mode (Recommended for Development)

For development, use the same Docker Compose stack as production. The web app runs with the Vite dev server on port 8080 (hot reload); the API runs on port 8000.

1) Copy env template and set values (for web/Supabase):

```bash
cp .env.example .env
# set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env
```

2) Start the stack (with logs in the foreground, or add `-d` for detached):

```bash
./docker-compose.sh up --build
```

**Development URLs:**
- Web: <http://localhost:8080> (Vite dev server with hot reload)
- API: <http://localhost:8000>

**Development Commands:**
- `./docker-compose.sh up --build` - Start stack (omit `-d` to see logs)
- `./docker-compose.sh up --build -d` - Start stack in background
- `docker compose down` - Stop all services
- `docker compose logs -f` - Follow all logs
- `docker compose logs -f api` - Follow API logs only
- `docker compose logs -f web` - Follow web logs only
- `docker compose exec api sh` - Open shell in API container
- `docker compose exec web sh` - Open shell in web container

## Services

### API Service (Port 8000)

- Camera management endpoints
- Video recording controls
- File management

### Web Dashboard (Port 8080)

- User authentication via Supabase
- Experiment definition and management
- Camera control interface
- Video playback and analysis

### Media API (Port 8090)

- Video listing, thumbnails, transcoding

### Video Remote (Port 3001)

- Video browser UI

### Vision System Remote (Port 3002)

- Camera/vision control UI

### Scheduling Remote (Port 3003)

- Scheduling/availability UI

### MediaMTX (Ports 8554, 8889, 8189)

- RTSP and WebRTC streaming (config: [mediamtx.yml](mediamtx.yml))

Supabase services are currently commented out in `docker-compose.yml` and can be run via Supabase CLI (e.g. from `management-dashboard-web-app`). See [docs](docs/) for setup.

## Git Subtree Workflow

This repo vendors two upstream projects using git subtree, preserving their histories under `camera-management-api/` and `management-dashboard-web-app/`.

Configured remotes:

- `cameras` → <https://github.com/salirezav/USDA-Vision-Cameras.git> (branch: `master`)
- `web-origin` → <https://github.com/salirezav/pecan_experiments.git> (branch: `master`)

Pull latest upstream changes into subtrees:

```bash
# API (USDA-Vision-Cameras)
git subtree pull --prefix=camera-management-api cameras master

# Web (pecan_experiments)
git subtree pull --prefix=management-dashboard-web-app web-origin master
```

Push your changes back upstream (optional):

```bash
# API (push changes made under camera-management-api/ back to USDA-Vision-Cameras)
git subtree push --prefix=camera-management-api cameras master

# Web (push changes made under management-dashboard-web-app/ back to pecan_experiments)
git subtree push --prefix=management-dashboard-web-app web-origin master
```

Notes:

- Subtrees keep a single working copy with full history; no submodule init/update required.
- If you prefer a lighter top-level history, you can use `--squash` when adding/pulling, but pushing back becomes trickier.

## Development Tips

- API
  - Code lives under `camera-management-api/`. The compose service runs the full system via `python main.py --config config.compose.json`.
  - Camera SDK access from inside Docker on Windows may be limited; for hardware work you might run the API directly on the host.
  - Configuration: `camera-management-api/config.json` (see `camera-management-api/docs` for details).
  - Storage (recordings) is mapped to `camera-management-api/storage/` and ignored by git.

- Web
  - Code lives under `management-dashboard-web-app/` with a Vite dev server on port 8080 when run via Docker.
  - Environment: set `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` in `.env` (not committed).
  - Common scripts: `npm run dev`, `npm run build` (executed inside the container by compose).

## Troubleshooting

- Port already in use: change the mapped ports in `docker-compose.yml` or stop the conflicting process.
- File watching issues on Docker Desktop: `CHOKIDAR_USEPOLLING=true` is already set for the web container.
- API not starting: check container logs and verify Python deps (compose installs from `requirements.txt` or `pyproject.toml`).