Project: Jetsons Living

┌─────────────────────────────────────────────────────────────────────┐
│  USER DEVICES                                                        │
│  ┌────────────────────┐   ┌──────────────────────────────────────┐  │
│  │  Web browser       │   │  iOS / Android app (Capacitor)        │  │
│  │  (Amplify, HTTPS)  │   │  (static Next.js export)             │  │
│  └────────┬───────────┘   └──────────────┬───────────────────────┘  │
└───────────┼──────────────────────────────┼──────────────────────────┘
            │  HTTPS via Amplify                │
            ▼                                  ▼
┌────────────────────────────────────────────────────────────────────┐
│  CLOUD (AWS Amplify + MongoDB Atlas)                                │
│                                                                    │
│  Next.js app                                                       │
│  ├── Auth0 authentication                                         │
│  ├── GET /api/servers            ← lists user's paired devices    │
│  ├── POST /api/pair/generate     ← starts pairing (makes a code)  │
│  ├── GET  /api/pair/status       ← polls for device to complete   │
│  ├── POST /api/pair/claim        ← device calls this (no auth)    │
│  ├── POST /api/pair/complete     ← device finalises pairing       │
│  ├── POST /api/pair/update-url   ← device registers tunnel URL   │
│  └── GET  /api/stream/token      ← returns Auth0 JWT + edge URL   │
│                                                                    │
│  MongoDB Atlas: users, paired servers (with apiUrl), pairing codes│
└────────────────────────────────────────────────────────────────────┘
            │
            │  Each server.apiUrl resolves to:
            │  ① LAN: https://jms-edge.home.jetsonsliving.com
            │     (DNS A record → device LAN IP, Let's Encrypt cert via DNS-01)
            │  ② Remote: https://<id>.trycloudflare.com
            │     (Cloudflare tunnel, registered by device on boot)
            │
            ▼
┌────────────────────────────────────────────────────────────────────┐
│  JMS EDGE DEVICE (on-premise, in the customer's home/building)     │
│  Hardware: mini-PC or Raspberry Pi running Docker                  │
│                                                                    │
│  jms-api (Node.js/Express) — authenticated via Auth0 JWT          │
│  ├── GET /api/events              ← grouped event feed             │
│  ├── GET /api/events/search       ← Frigate semantic search       │
│  ├── GET /api/events/clips        ← filterable paginated clips    │
│  ├── GET /api/events/stats        ← analytics aggregation         │
│  ├── GET /api/frigate/*           ← transparent Frigate proxy     │
│  ├── GET /api/camera/:id/mse      ← live video (MSE stream)       │
│  ├── GET /api/storage/*           ← thumbnails, clip files        │
│  └── POST /api/admin/*            ← reboot, factory reset         │
│                                                                    │
│  Frigate (NVR)                                                     │
│  ├── Ingests RTSP camera streams                                  │
│  ├── Runs object detection (person, vehicle, animal, etc.)        │
│  ├── Stores clips + thumbnails at /mnt/storage/frigate/           │
│  └── Semantic search via sentence-transformers (small model)      │
│                                                                    │
│  MongoDB (local)   ← eventSync.ts polls Frigate every 10s         │
│  Caddy (TLS)       ← DNS-01 cert for jms-edge.home.jetsonsliving.com│
│  Go2RTC            ← WebRTC / MSE stream relay                    │
└────────────────────────────────────────────────────────────────────┘

1. Customer receives JMS device (mini-PC/Pi) pre-loaded with jms-edge firmware

2. Device boots for the first time (no /etc/jms/device.json):
   └── Broadcasts WiFi hotspot "JMS-SETUP" at 192.168.4.1
   └── Runs captive portal web server on port 80

3. Customer connects laptop/phone to JMS-SETUP WiFi

4. Browser opens http://192.168.4.1 → device's setup UI
   └── Customer is prompted for: pairing code + home WiFi credentials

5. In the JMS app (jetsons-management-system):
   └── Settings → Add Server → "Add Server" modal opens
   └── App calls POST /api/pair/generate → gets a 6-char code (e.g. "K7X2M9")
   └── Code displayed on screen for the customer to type into the device UI

6. Customer types the code into the device captive portal:
   └── Device calls POST /api/pair/claim (cloud) → validates code, creates Server record,
       returns { deviceSecret }
   └── Device configures WiFi via nmcli
   └── Device calls POST /api/pair/complete (cloud) → marks pairing complete
   └── Device saves { deviceId, deviceSecret } to /etc/jms/device.json
   └── Device connects to home WiFi, Docker stack starts

7. App polls GET /api/pair/status?code=K7X2M9 every 3 seconds
   └── When pairing completes → returns serverId
   └── App transitions to camera list, device shows up as online

8. On every subsequent boot, device calls POST /api/pair/update-url with its
   Cloudflare tunnel URL so the cloud always knows how to reach it remotely

9. Customer is now on the cameras home screen, their device is paired

Settings → Configuration → Add Camera
→ Frigate RTSP stream integration
→ Camera name, stream URL, group assignment
→ jms-edge applies the new Frigate config and restarts the detection pipeline

api/src/
  index.ts          — Express app, DB connection, route mounting
  config.ts         — Env vars (FRIGATE_URL, MONGO_URI, AUTH0_DOMAIN, etc.)
  middleware/auth.ts — tokenFromQueryToHeader + checkJwt (Auth0 JWT validation)
  routes/
    events.ts       — GET /api/events, GET /api/events/search
    frigate.ts      — Transparent proxy: GET /api/frigate/* → Frigate API
    camera.ts       — Live streams: MSE, WebRTC, MJPEG
    storage.ts      — Authenticated file access (thumbnails, clips)
    admin.ts        — Reboot, restart-service, factory-reset
  models/Event.ts   — Mongoose schema for Frigate events
  services/eventSync.ts — Polls Frigate every 10s, upserts to MongoDB

setup/              — Captive portal server (runs before Docker on first boot)
  src/server.ts     — HTTP server at 192.168.4.1 (setup UI + POST /api/setup)
  src/provision.ts  — Calls cloud pair/claim + pair/complete
  src/network.ts    — WiFi config via nmcli
  start.sh          — Boot entrypoint (checks device.json → setup or normal)

{
  _id: string;           // Frigate event ID
  cameraId: string;      // Camera name from Frigate config (e.g. "front_door")
  labels: string[];      // ["person", "car"] — from Frigate detection
  startTime: Date;
  thumbnailPath: string; // Relative path under /mnt/storage/
}

interface ClipDto {
  id: string;           // Frigate event ID
  cameraId: string;
  labels: string[];
  startTime: string;    // ISO 8601
  thumbnailPath: string;
}

interface StatsResponse {
  total: number;
  labelCounts: Record<string, number>;  // { person: 780, vehicle: 300 }
  byHour: Array<{ hour: number; count: number }>;
  byCamera: Array<{ cameraId: string; count: number }>;
}

docker compose --profile coder ps

cd /srv/shared/projects/jetsons-living
source .venv/bin/activate
PYTHONPATH=src python -m jetsons_crew.main

# Edit .env and set all *_MODEL values to claude-sonnet, then run normally

# On the JMS device (SSH in)
git pull origin feat/clips-and-stats-api
docker compose up -d --force-recreate --build jms-api