# Doggo Detection — Architecture & Rebuild Reference Real-time dog detection dashboard. Public at **doggosonmystreet.com**. This document is the mental model for the system. If rebuilding from backup, read this first, then follow RESTORE.txt in any `daily/` backup folder. --- ## Pipeline ``` Reolink camera (RTSP, H.265) -> ffmpeg (decode, scale 1920x1080, bgr24 raw pipe) -> detect.py: YOLO (person/dog/bike detection) -> crop saved to ~/camera/dogs/ -> matcher.py: CLIP embed -> MegaDescriptor match against known dogs -> Claude Vision (breed + coat color + walking direction) -> SQLite (dogs.db) -> dashboard.html renders it ``` ## Processes Two Flask apps, both started from `~/camera` with the venv active: - **detect.py** — port 5000, public-facing (via Cloudflare tunnel). Serves the dashboard, live video, image files, and proxies DB endpoints to matcher. - **matcher.py** — port 5001, internal only. Owns the DB writes, matching logic, Claude Vision calls, and most `/db/*` endpoints. detect.py proxies many `/db/*` routes through to matcher on 5001. If a public endpoint returns 404, check whether it exists in detect.py as a proxy (it may only live in matcher.py). Mac Mini user: `alclaw`. Working dir: `~/camera/`. ## Vision model Claude Vision does breed + coat color + direction per new dog. Model constant in matcher.py: `VISION_MODEL`. Currently **claude-sonnet-4-6** (switched up from Haiku for better breed accuracy; Haiku mis-ID'd common breeds like Shiba Inu). CLIP is ONLY for matching similarity — Claude Vision does not depend on CLIP quality. ## Pages - `/` — dashboard.html (desktop 3-col, mobile single-col). Public. - `/picker` — same/different dog triage. Public (auth removed intentionally). - `/direction` — LEFT/RIGHT (EAST/WEST) direction tagging. Public. - `/review` — full dog DB management. **Auth required** (Cloudflare Access + cookie). Never make this public. ## Auth model - `/review` and all destructive `/db/*` mutations are gated by `@require_auth` (checks the `doggo_auth` cookie == SECRET in secret.txt). - Cookie is set by hitting `/auth?token=` once per browser (lasts 1yr). - Local access: `http://:5000/auth?token=` then `/review`. - picker and direction are intentionally NOT gated (public can submit triage). - Cloudflare Access adds a second gate on `/review` at the edge (Google login). ## Data model (see schema.sql for exact columns) - `dogs` — one row per unique dog. breed, color, reference_crop, clip_embedding, visit_count, first/last_seen. Breed/color/etc. stay with the DOG. - `processed` — every crop file and which dog it matched. - `crop_directions` — direction per CROP (a dog walks both ways, so direction is per-crop, not per-dog). - `direction_reviewed` — cross-device tracking of which crops were hand-reviewed. - `picker_queue` — new/known dog pairs awaiting human triage. Coat colors: white, black, brown, gray, mixed dark, mixed light. (gray was added later — it must appear in matcher.py VALID sets, the vision prompt, the review.html picker, AND colorStyles.) ## Infra - **Hosting**: Cloudflare Tunnel to port 5000 only. Port 5001 is never exposed. - **Camera**: Reolink over RTSP. The camera URL and login live in rtsp_url.txt (git-ignored). Use the H.265 main stream; the H.264 substream breaks the pipeline. ## Design tokens Fonts: VT323 (body), Press Start 2P (headers/buttons). Colors: gold #f4b942, pink #ff4fa0, coral #e0524f, green #7ed957, cyan #5ec8d8, purple #7c3aed, home-banner brown #b45309. ## Coding rules for this project - Always deliver FULL html files, never patches. - Deploy by moving the file into place, then grep a sentinel string to confirm. - After deploy, restart the affected process (detect.py or matcher.py).