Docs: add subtree workflow and Docker Compose quick start to README

README.md

@@ -1,38 +1,101 @@
 # USDA Vision
 
-A unified project combining camera API services and web dashboard for USDA vision experiments.
+A unified monorepo combining the camera API service and the web dashboard for USDA vision experiments.
 
 ## Project Structure
 
 - `api/` - Python API service for camera management (USDA-Vision-Cameras)
 - `web/` - React web dashboard for experiment management (pecan_experiments)
 
-## Getting Started
+## Quick Start (Docker Compose)
+
+1) Copy env template and set values (for web/Supabase):
 
 ```bash
-# Start all services
-docker-compose up -d
-
-# Development mode
-docker-compose -f docker-compose.dev.yml up
+cp .env.example .env
+# set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in .env
 ```
 
+2) Start the stack:
+
+```bash
+docker compose up --build
+```
+
+- Web: <http://localhost:5173>
+- API: <http://localhost:8000>
+- MQTT broker: localhost:1883
+
+To stop: `docker compose down`
+
 ## Services
 
 ### API Service (Port 8000)
+
 - Camera management endpoints
 - Video recording controls
 - File management
 
-### Web Dashboard (Port 3000)
+### Web Dashboard (Port 5173)
+
 - User authentication via Supabase
 - Experiment definition and management
 - Camera control interface
 - Video playback and analysis
 
-## Development
+### MQTT Broker (Port 1883)
 
-Each service can be developed independently:
+- Local Mosquitto broker for development and integration testing
 
-- API: See `api/README.md`
-- Web: See `web/README.md`
+## Git Subtree Workflow
+
+This repo vendors two upstream projects using git subtree, preserving their histories under `api/` and `web/`.
+
+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=api cameras master
+
+# Web (pecan_experiments)
+git subtree pull --prefix=web web-origin master
+```
+
+Push your changes back upstream (optional):
+
+```bash
+# API (push changes made under api/ back to USDA-Vision-Cameras)
+git subtree push --prefix=api cameras master
+
+# Web (push changes made under web/ back to pecan_experiments)
+git subtree push --prefix=web 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 `api/`. The compose service runs `uvicorn usda_vision_system.api.server:app --reload` by default.
+  - Camera SDK access from inside Docker on Windows may be limited; for hardware work you might run the API directly on the host.
+  - Configuration: `api/config.json` (see `api/docs` for details).
+  - Storage (recordings) is mapped to `api/storage/` and ignored by git.
+
+- Web
+  - Code lives under `web/` with a Vite dev server on port 5173.
+  - 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`).