FluidWatch — Smart IV Drip System

An ESP32-CAM unit mounted on an IV stand photographs the bag on a timer. A backend scores each photo with a trained fill-level model, derives volume, flow rate and status, and pushes live updates to a web dashboard that shows nursing staff every bed and raises an alert when one goes critical.

Live: https://frontend-topaz-xi-xu5rpbpic5.vercel.app

This README is the project's only documentation file.

• Repository layout
• How the pieces connect
• Quick start (local)
• Backend — server/
• Fill-level model — server/app/cv/ + ml-model-training/
• Dashboard — frontend/
• Database & auth — supabase/
• Firmware — firmware/esp32-cam/
• Testing & CI
• Security
• Deployment

Repository layout

frontend/             Ward dashboard - TanStack Start, React, Tailwind.     -> Vercel
server/               FastAPI backend - ingest, fill-level model, storage,  -> Render
                      exports, WebSocket feeds.
supabase/             Database schema (migrations) for staff auth, roles
                      and ward settings. Supabase CLI project.
firmware/esp32-cam/   ESP32-CAM firmware (PlatformIO) - capture + upload.   -> serial once, then OTA
firmware/tools/       fleet.py - remote settings, photos and OTA over MQTT.
ml-model-training/    Training scripts and model artifacts.
.github/              CI workflow and Dependabot config.
docs/screenshots/     Images used in this README.
docker-compose.yml    Runs the backend locally in Docker.

Each part is self-contained: its own dependencies, config and ignore rules, and its own CI job.

How the pieces connect

ESP32-CAM  --HTTP POST image-->  FastAPI (server/)  --WebSocket-->  Dashboard (frontend/)
                                   fill-level model,        /ws/bedfeed    live bed cards
                                   SQLite, CSV/XLSX export                       |
                                                                                 v
                                                              Supabase (supabase/): staff login,
                                                              roles, ward settings

• The camera uploads a JPEG to POST /api/v1/frames. The server runs the model on it, turns the fill % into a full reading (volume, flow rate from the previous reading, status and alert), stores it and broadcasts it.
• server/app/bedfeed.py reshapes each reading into the {id, bed, patient, fluid, flow, level, status, auxClass, battery, wifi} message that frontend/src/lib/fluidwatch.ts's applyLiveUpdate() merges into the bed list. A device the dashboard hasn't seen before becomes a new bed card automatically, so no provisioning is needed.
• Device statuses map to dashboard statuses: NORMAL → STABLE, LOW_LEVEL → WATCH, EMPTY/OCCLUSION/ERROR → CRITICAL.
• Supabase handles only staff accounts and the ward_settings row (alert thresholds and the backend's WebSocket URL). The backend never talks to Supabase.

Quick start (local)

Backend (Python 3.11):

cd server
python -m venv .venv
.venv\Scripts\activate              # Windows;  source .venv/bin/activate elsewhere
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Or with Docker, from the repo root: API_AUTH_TOKEN=<token> docker compose up --build.

Dashboard (Node 22):

cd frontend
npm install
npm run dev                         # http://localhost:8080

Sign up. The first account created becomes the ward admin. Open /dashboard and click Connect ward server. Without a live connection the dashboard runs a built-in simulator on six demo beds, so the UI is never empty.

Firmware: see Firmware. Without hardware, open http://localhost:8000/docs, use POST /api/v1/frames to upload any photo, and watch it appear on the dashboard.

Backend — server/

FastAPI service that ingests camera frames (and plain JSON readings), runs the fill-level model, stores readings, exports them, and pushes live updates over WebSockets.

Code map

Path	Role
app/main.py	App setup, CORS, /health
app/config.py	Settings from env / .env (see below)
app/db.py, app/models.py, app/schemas.py	SQLAlchemy engine and the Reading table / Pydantic shapes
app/routers/frames.py	POST /api/v1/frames - image → model → reading; GET /latest serves the last photo
app/routers/readings.py	JSON ingest, list/latest, CSV/XLSX export, bearer-token auth
app/routers/devices.py	One row per device from its latest reading, with an online flag (seen in the last 90s)
app/routers/ws.py, app/ws_manager.py	/ws/readings and /ws/bedfeed broadcast feeds
app/bedfeed.py	Reading → dashboard bed-card message
app/cv/	Fill-level model and reading derivation - see Fill-level model
app/frame_storage.py	Keeps only the latest JPEG per device (data/frames/)

Readings are capped at 1000 per device (oldest pruned) so storage stays predictable during long demos.

This is the beginning of the README. Read the rest at the original. Read the full README ↗