navidocs/intelligence/session-2/camera-integration-spec.md

Camera & Remote Monitoring Integration Specification

NaviDocs Boat Peace-of-Mind System

Agent ID: S2-H04 Task: Camera & Remote Monitoring Integration (STICKY!) Status: Complete Date: 2025-11-13

---

Executive Summary

This specification describes a comprehensive camera and remote monitoring system for boat owners, enabling "is my boat OK?" peace of mind through Home Assistant integration, real-time alerts, snapshot galleries, and optional computer vision for equipment detection. The system prioritizes mobile-first UI, seamless integration with existing NaviDocs architecture, and security hardening for both webhook endpoints and snapshot storage.

---

1. Home Assistant Integration Architecture

1.1 Webhook Architecture (NaviDocs ← HA Events)

Flow Diagram:

Home Assistant Instance (on boat or cloud)
    ↓ (webhook POST)
NaviDocs Webhook Receiver (/api/webhooks/events/home-assistant)
    ↓ (validate signature + rate limit)
Event Bus (Redis pub/sub)
    ↓ (fan-out to handlers)
├─→ Snapshot Storage Service
├─→ Alert Notification Engine
├─→ Timeline Logger (IF.TTT audit trail)
└─→ WebSocket broadcast (real-time dashboard updates)

1.2 Webhook Receiver Endpoint

Endpoint: POST /api/webhooks/events/home-assistant

Authentication:

• HA sends webhook with X-HA-Signature header (HMAC-SHA256)
• NaviDocs validates signature against stored HA API token
• Rate limiting: 100 events/minute per boat (prevents DDoS from compromised HA instance)
• Tenant isolation: webhook must include boat_id + signature verification

Request Payload Schema:

{
  "boat_id": "boat-uuid-12345",
  "event_type": "motion_detected | battery_low | bilge_pump_triggered | camera_offline | network_interrupted | manual_snapshot_requested",
  "timestamp": "2025-11-13T14:32:00Z",
  "camera_id": "hikvision-deck-cam-1",
  "camera_name": "Deck Camera (Port)",
  "event_data": {
    "severity": "info | warning | critical",
    "message": "Motion detected on deck",
    "confidence": 0.95,
    "ai_detection": {
      "object_class": "person | boat | equipment | animal | vehicle",
      "confidence": 0.87
    },
    "battery_percentage": 45,
    "signal_strength": -65,
    "location_zone": "deck | salon | galley | helm | engine_room | bilge | hull"
  },
  "snapshot_url": "https://ha-instance.local:8123/api/camera_proxy/camera.deck_camera?token=xxx",
  "video_url": "rtsp://user:pass@ha-instance.local:554/stream1",
  "metadata": {
    "ha_integration": "hikvision | reolink | generic_onvif",
    "camera_model": "Hikvision DS-2CD2043G0-I",
    "firmware_version": "V5.4.41"
  }
}

Response (Success):

{
  "status": "received",
  "event_id": "if://event/navidocs/boat-123/motion-2025-11-13-14-32-00",
  "processing_status": "queued",
  "snapshot_storage_url": "https://navidocs-api.example.com/api/snapshots/{snapshot_id}",
  "alert_sent": true,
  "alert_channels": ["push_notification", "email"]
}

1.3 Supported Camera Brands & Integration

Primary Integration: Home Assistant Camera Platform

• Automatically supports 50+ camera brands via HA plugins
• Examples: Hikvision, Reolink, AXIS, Dahua, Netgear, Ubiquiti, Wyze

Integration Method:

1. User installs Home Assistant (on Raspberry Pi or NUC in boat cabin)
2. Adds camera integration in HA (simple YAML config)
3. Creates webhook automation in HA:

   automation:
     - alias: "NaviDocs Motion Alert"
       trigger:
         platform: state
         entity_id: binary_sensor.deck_motion_sensor
         to: "on"
       action:
         - service: rest_command.navidocs_webhook
           data:
             event_type: "motion_detected"
             camera_id: "deck-cam-1"
   

4. NaviDocs webhook secret stored in HA configuration

Marine-Specific Cameras (Optional Integrations):

• Cradlepoint: Cellular backup for internet connectivity
• StarLink: High-latency satellite internet (HA can work over it)
• Ubiquiti UniFi: Professional marine-grade wireless
• Battery monitoring: Victron SmartShunt feeds battery % to HA

1.4 MQTT Broker Integration (Real-Time Events)

Optional: For boats already using MQTT infrastructure

MQTT Topics:

navidocs/{boat_id}/camera/{camera_id}/snapshot
navidocs/{boat_id}/alerts/{alert_type}/{severity}
navidocs/{boat_id}/status/online
navidocs/{boat_id}/telemetry/battery_voltage

Message Format:

{
  "boat_id": "boat-uuid",
  "camera_id": "deck-cam-1",
  "timestamp": "2025-11-13T14:32:00Z",
  "event": "motion_detected",
  "confidence": 0.95,
  "snapshot_id": "snap-uuid-xxx",
  "processing": "queued"
}

Bridge Design:

• HA MQTT integration sends to broker
• NaviDocs MQTT subscriber processes events (same as webhook, but async)
• Fallback to webhook if MQTT unavailable (reliability)

---

2. Camera Snapshot Storage Schema

2.1 Database Table: camera_snapshots

Purpose: Store metadata + links to snapshot files, enable gallery queries with time-series retrieval

Schema:

CREATE TABLE camera_snapshots (
  -- Primary Key
  id TEXT PRIMARY KEY,  -- uuid: snap-boat123-2025-11-13-14-32-00

  -- Foreign Keys & Ownership
  boat_id TEXT NOT NULL,  -- Links to boat
  camera_id TEXT NOT NULL,  -- Physical camera identifier
  FOREIGN KEY (boat_id) REFERENCES entities(id),

  -- Event Information
  event_type TEXT NOT NULL,  -- 'motion', 'alert', 'manual', 'battery_low', 'bilge', 'scheduled'
  event_severity TEXT DEFAULT 'info',  -- 'info', 'warning', 'critical'
  event_message TEXT,  -- "Motion detected on deck"
  confidence REAL,  -- 0.0-1.0 (for AI detections)

  -- Computer Vision Results (Optional)
  cv_analysis JSON,  -- {object_classes: [{class: "person", conf: 0.95}], detected_objects: [...]}
  ai_detection_enabled BOOLEAN DEFAULT FALSE,
  detected_equipment TEXT,  -- Detected tender, electronics, etc.

  -- Timestamp Information
  snapshot_timestamp DATETIME NOT NULL,  -- When photo was taken
  received_timestamp DATETIME NOT NULL,  -- When webhook received
  processed_timestamp DATETIME,  -- When CV analysis completed

  -- Storage Information
  storage_path TEXT NOT NULL,  -- s3://navidocs-snapshots/boat-123/2025-11-13/snap-uuid.jpg
  thumbnail_path TEXT,  -- s3://navidocs-snapshots/boat-123/2025-11-13/snap-uuid-thumb.jpg
  file_size_bytes INTEGER,
  image_hash TEXT,  -- SHA-256 hash for deduplication + IF.TTT compliance

  -- Metadata
  camera_name TEXT,
  camera_model TEXT,
  camera_zone TEXT,  -- 'deck', 'salon', 'galley', 'helm', 'engine_room', 'bilge', 'hull'
  battery_percentage INTEGER,  -- Camera battery %
  signal_strength INTEGER,  -- WiFi/cellular signal (dBm)

  -- Related Data
  linked_alert_id TEXT,  -- FK to alerts table
  linked_inventory_items TEXT,  -- JSON array of inventory item UUIDs detected

  -- Retention & Cleanup
  retention_days INTEGER DEFAULT 30,
  marked_for_deletion BOOLEAN DEFAULT FALSE,
  deletion_scheduled_at DATETIME,

  -- Metadata
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,

  -- Indexing
  UNIQUE(boat_id, camera_id, snapshot_timestamp),
  INDEX idx_boat_timestamp (boat_id, snapshot_timestamp DESC),
  INDEX idx_event_type (boat_id, event_type, snapshot_timestamp DESC),
  INDEX idx_retention (boat_id, marked_for_deletion, deletion_scheduled_at),
  FULLTEXT INDEX idx_search (event_message, detected_equipment)
);

2.2 Computer Vision Analysis Table

Purpose: Store ML model inference results separately for querying without loading image files

CREATE TABLE camera_cv_analysis (
  id TEXT PRIMARY KEY,
  snapshot_id TEXT NOT NULL UNIQUE,
  boat_id TEXT NOT NULL,

  -- Model Information
  model_name TEXT,  -- 'YOLOv8-boat-equipment', 'YOLOv8-person-detection'
  model_version TEXT,
  inference_time_ms FLOAT,

  -- Detection Results (JSON because variable number of objects)
  detections JSON,  -- [
                    --   {class: "tender", confidence: 0.94, bbox: [x, y, w, h]},
                    --   {class: "person", confidence: 0.87, bbox: [x, y, w, h]},
                    --   {class: "electronics", confidence: 0.78, bbox: [x, y, w, h]}
                    -- ]

  -- Summary Statistics
  person_detected BOOLEAN,
  tender_detected BOOLEAN,
  equipment_detected BOOLEAN,
  anomaly_score FLOAT,  -- 0.0-1.0 (unusual vs historical average)

  -- Thresholds & Alerts
  alert_triggered BOOLEAN,
  alert_reason TEXT,  -- Why alert was triggered

  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (snapshot_id) REFERENCES camera_snapshots(id),
  FOREIGN KEY (boat_id) REFERENCES entities(id),
  INDEX idx_detections (boat_id, created_at DESC)
);

2.3 Auto-Cleanup Policy

Retention Rules:

• Default: Keep 30 days
• Critical/Alert snapshots: Keep 90 days
• Manual snapshots (user bookmarked): Keep indefinitely
• Thumbnail index: Keep forever (small file size)

Cleanup Implementation:

-- Daily cleanup job (BullMQ scheduled job)
SELECT * FROM camera_snapshots
WHERE boat_id = $1
  AND marked_for_deletion = FALSE
  AND snapshot_timestamp < DATETIME('now', '-30 days')
  AND event_type NOT IN ('critical', 'alert')
  AND id NOT IN (
    SELECT snapshot_id FROM bookmarks WHERE entity_type = 'snapshot'
  );

-- Mark for deletion (soft delete, 7-day grace period)
UPDATE camera_snapshots
SET marked_for_deletion = TRUE, deletion_scheduled_at = DATETIME('now', '+7 days')
WHERE id IN (...);

-- Hard delete after grace period
DELETE FROM camera_snapshots
WHERE marked_for_deletion = TRUE
  AND deletion_scheduled_at < DATETIME('now');

Storage Tier Strategy:

• Hot tier (7 days): S3 Standard - frequently accessed
• Warm tier (7-30 days): S3 Intelligent-Tiering
• Cold tier (30+ days): S3 Glacier (archive critical/alert photos)

2.4 Thumbnail Generation

Automatic Thumbnail Pipeline:

// server/workers/snapshot-thumbnail-worker.js
module.exports = {
  async processSnapshotThumbnail(jobData) {
    const { snapshotId, storagePath } = jobData;

    // 1. Download original from S3
    const originalImage = await s3.getObject(storagePath);

    // 2. Generate thumbnails (multiple sizes for responsive mobile)
    const thumbnails = {
      'thumb-140w': await sharp(originalImage)
        .resize(140, 105, { fit: 'cover' })
        .jpeg({ quality: 75 })
        .toBuffer(),
      'thumb-280w': await sharp(originalImage)
        .resize(280, 210, { fit: 'cover' })
        .jpeg({ quality: 80 })
        .toBuffer(),
      'thumb-560w': await sharp(originalImage)
        .resize(560, 420, { fit: 'cover' })
        .jpeg({ quality: 85 })
        .toBuffer()
    };

    // 3. Upload thumbnails to S3
    for (const [name, data] of Object.entries(thumbnails)) {
      await s3.putObject(`${storagePath.replace('.jpg', '')}-${name}.jpg`, data);
    }

    // 4. Update database with thumbnail paths
    await db.query(
      'UPDATE camera_snapshots SET thumbnail_path = ? WHERE id = ?',
      [`${storagePath.replace('.jpg', '')}-thumb-280w.jpg`, snapshotId]
    );
  }
};

---

3. API Endpoints (Webhook Receiver, Snapshot Gallery, Live Feed)

3.1 Webhook Receiver Endpoint

POST /api/webhooks/events/home-assistant

Already detailed in Section 1.2. Key security features:

• HMAC-SHA256 signature validation
• Rate limiting: 100 events/minute
• Tenant isolation via boat_id verification
• Async processing via BullMQ (non-blocking)

3.2 Snapshot Gallery API

GET /api/boats/{boat_id}/snapshots

Query Parameters:

?event_type=motion,alert,manual  -- Filter by event
?camera_id=deck-cam-1            -- Filter by camera
?severity=critical,warning         -- Filter by severity
?from=2025-11-10&to=2025-11-13   -- Date range
?skip=0&limit=20                 -- Pagination
?sort=timestamp_desc              -- Sort order
?search=tender,person             -- CV detection search

Response:

{
  "status": "success",
  "data": {
    "total_snapshots": 245,
    "page": 1,
    "limit": 20,
    "snapshots": [
      {
        "id": "snap-uuid-xxx",
        "timestamp": "2025-11-13T14:32:00Z",
        "event_type": "motion",
        "severity": "warning",
        "camera_name": "Deck Camera",
        "camera_zone": "deck",
        "thumbnail_url": "https://api.navidocs.com/snapshots/snap-xxx/thumb-280w",
        "full_image_url": "https://api.navidocs.com/snapshots/snap-xxx/full",
        "cv_detections": {
          "person_detected": true,
          "confidence": 0.94,
          "objects": [
            {"class": "person", "confidence": 0.94},
            {"class": "boat", "confidence": 0.87}
          ]
        },
        "metadata": {
          "battery_percentage": 85,
          "signal_strength": -55,
          "camera_model": "Hikvision DS-2CD2043G0-I"
        }
      },
      // ... more snapshots
    ]
  }
}

Security:

• Tenant isolation: Only return snapshots for authenticated boat_id
• Auth: JWT bearer token required
• Rate limiting: 60 requests/minute per user
• Image delivery: S3 signed URLs (10-minute expiry)

3.3 Individual Snapshot Retrieval

GET /api/snapshots/{snapshot_id}

Response: Redirect to S3 signed URL (no sensitive data exposed)

GET /api/snapshots/{snapshot_id}/metadata

Response:

{
  "id": "snap-uuid",
  "boat_id": "boat-123",
  "camera_id": "deck-cam-1",
  "timestamp": "2025-11-13T14:32:00Z",
  "event_type": "motion_detected",
  "severity": "warning",
  "cv_analysis": {
    "model": "YOLOv8-boat-equipment",
    "detections": [
      {"class": "person", "confidence": 0.94, "bbox": [100, 50, 200, 300]},
      {"class": "tender", "confidence": 0.87, "bbox": [50, 300, 400, 450]}
    ]
  },
  "linked_inventory": [
    {"item_id": "inv-tender-001", "name": "Zodiac 310"}
  ]
}

3.4 Live Camera Feed Proxy

GET /api/boats/{boat_id}/live-feeds

Purpose: Discover available live feeds from Home Assistant instance

Response:

{
  "status": "success",
  "data": {
    "boat_id": "boat-123",
    "ha_status": "connected",
    "ha_version": "2025.11.0",
    "feeds": [
      {
        "camera_id": "deck-cam-1",
        "camera_name": "Deck Camera",
        "model": "Hikvision DS-2CD2043G0-I",
        "stream_types": ["rtsp", "hls", "http_mjpeg"],
        "stream_urls": {
          "rtsp": "rtsp://ha-instance.local:554/stream1",
          "hls": "http://ha-instance.local:8123/api/hls/camera.deck_camera/playlist.m3u8"
        },
        "ha_entity_id": "camera.deck_camera",
        "battery_percentage": 85,
        "signal_strength": -55,
        "last_frame_timestamp": "2025-11-13T14:32:00Z",
        "recording_enabled": true
      },
      // ... more cameras
    ]
  }
}

Security Notes:

• HLS endpoint proxied through NaviDocs (HTTPS, auth required)
• RTSP streams exposed to mobile app (app handles decryption)
• Rate limiting: 10 stream requests/minute (prevent abuse)

3.5 Alert Creation API

POST /api/boats/{boat_id}/alerts

Request:

{
  "snapshot_id": "snap-uuid",
  "alert_type": "motion | intruder_detected | equipment_detected | battery_critical",
  "severity": "info | warning | critical",
  "message": "Motion detected on deck at 14:32",
  "notify_channels": ["push", "email", "sms"],
  "auto_notify_users": true
}

Response:

{
  "alert_id": "alert-uuid",
  "status": "created",
  "notifications_sent": {
    "push": {
      "status": "queued",
      "target_devices": ["user-device-1", "user-device-2"]
    },
    "email": {
      "status": "queued",
      "recipients": ["owner@email.com"]
    },
    "sms": {
      "status": "queued",
      "recipients": ["+33612345678"]
    }
  }
}

3.6 Statistics & Dashboard API

GET /api/boats/{boat_id}/camera-stats

Response:

{
  "boat_id": "boat-123",
  "period": "7d",
  "statistics": {
    "total_snapshots": 245,
    "snapshots_by_type": {
      "motion": 142,
      "alert": 58,
      "manual": 32,
      "scheduled": 13
    },
    "camera_uptime": {
      "deck-cam-1": 0.98,
      "salon-cam-1": 0.95
    },
    "top_detection_types": [
      {"class": "person", "count": 12},
      {"class": "boat", "count": 5}
    ],
    "storage_used_gb": 2.3,
    "storage_quota_gb": 10,
    "retention_days": 30
  }
}

---

4. Mobile-First UI Wireframes

4.1 Main Camera Dashboard (Home Screen)

Screen 1: Quick Check ("Is my boat OK?")

┌──────────────────────────┐
│ 📍 BOAT: "Riviera Plaisance" │
│      Docked: Port Grimaud  │
├──────────────────────────┤
│  🔴 LATEST SNAPSHOT       │
│  ┌──────────────────────┐ │
│  │   [DECK CAM IMAGE]   │ │
│  │   2 min ago          │ │
│  └──────────────────────┘ │
│  • Motion detected        │
│  • Person detected (94%)  │
│  • Battery: 85%           │
│  • Signal: Strong         │
├──────────────────────────┤
│ [REFRESH] [GALLERY] [LIVE]│
├──────────────────────────┤
│  ⚠️ 3 ALERTS (last 7d)   │
│  • Motion (Deck) - 11/13  │
│  • Battery Low (Port) - 11/13 │
│  • Manual Check - 11/13   │
├──────────────────────────┤
│ [🎥 CAMERAS] [⚙️ SETTINGS]│
└──────────────────────────┘

UI Components:

• Large snapshot thumbnail (280px width, 16:9 aspect)
• Timestamp relative ("2 min ago")
• Quick stats overlay: motion, people, battery
• 1-tap refresh for latest snapshot
• Tap image → full screen viewer
• Tap alert → details + linked snapshot

4.2 Camera Gallery (Chronological Feed)

Screen 2: Snapshot Gallery (Infinite Scroll)

┌──────────────────────────┐
│ 🎥 CAMERA GALLERY        │
│ [Filter ▼] [Sort ▼]     │
├──────────────────────────┤
│📅 Nov 13, 2025          │
│ ┌─────────┬─────────┐   │
│ │[THUMB]  │[THUMB]  │   │
│ │14:32    │14:15    │   │ 2x2 grid layout
│ │Motion   │Manual   │   │
│ └─────────┴─────────┘   │
│ ┌─────────┬─────────┐   │
│ │[THUMB]  │[THUMB]  │   │
│ │13:47    │13:22    │   │
│ │Alert    │Motion   │   │
│ └─────────┴─────────┘   │
│                          │
│📅 Nov 12, 2025          │
│ ┌─────────┬─────────┐   │
│ │[THUMB]  │[THUMB]  │   │
│ │22:15    │20:03    │   │
│ │Battery  │Manual   │   │
│ │Low      │         │   │
│ └─────────┴─────────┘   │
│                          │
│ [Load More...]           │
└──────────────────────────┘

FILTER PANEL (Slide-up):
├─ Event Type: ☑️ All ☑️ Motion ☐ Alert ☐ Manual
├─ Camera: ☑️ All ☑️ Deck ☑️ Salon ☐ Helm
├─ Severity: ☑️ All ☑️ Warning ☐ Critical
├─ Date Range: [Picker]
└─ [APPLY FILTERS]

UI Features:

• Infinite scroll (lazy load)
• Date-grouped sections (collapsible)
• 2x2 thumbnail grid (140px × 105px each)
• Filter panel slide-up (bottom sheet)
• Tap thumbnail → full screen + details

4.3 Snapshot Details & Viewer

Screen 3: Full Screen Image Viewer

┌──────────────────────────┐
│ ← [Gallery]    [More ⋯]  │ Header
├──────────────────────────┤
│                          │
│    ┌──────────────────┐  │
│    │                  │  │
│    │  [FULL IMAGE]    │  │ Swipeable
│    │                  │  │ full screen
│    └──────────────────┘  │
│                          │
├──────────────────────────┤
│ Deck Camera              │
│ 2025-11-13 14:32:00     │ Timestamp
│ Motion Detected          │ Event type
├──────────────────────────┤
│ ANALYSIS:                │
│ 🟢 Person detected (94%) │
│ 🟡 Boat detected (87%)   │
│ 🔵 Equipment detected    │
│ • Tender (Zodiac 310)    │
├──────────────────────────┤
│ METADATA:                │
│ 🔋 Battery: 85%          │
│ 📶 Signal: -55dBm        │
│ 🎥 Model: Hikvision...   │
├──────────────────────────┤
│ [Share] [Save] [Delete]  │
└──────────────────────────┘

MORE MENU (Dropdown):
├─ Link to Inventory Item
├─ Link to Alert
├─ Set as Boat Profile Pic
├─ Download Original
├─ Delete Snapshot
└─ Report Issue

CV Detection Visualization:

• Bounding boxes overlaid on image (toggleable)
• Confidence score displayed
• Tap detection → auto-populate inventory if equipment detected

4.4 Live Camera Feed

Screen 4: Live View (If HLS Available)

┌──────────────────────────┐
│ ← [Back]   Deck Camera   │
├──────────────────────────┤
│  ┌──────────────────────┐│
│  │  [LIVE STREAM]       ││
│  │  Connected           ││
│  │  720p 30fps          ││
│  │  Bitrate: 2.5Mbps    ││
│  │                      ││
│  │  [PLAY] [PAUSE]      ││
│  │                      ││
│  └──────────────────────┘│
├──────────────────────────┤
│ Connection Status:       │
│ ✅ Home Assistant        │
│ ✅ Camera Online         │
│ ✅ Streaming             │
│ ✅ Battery: 92%          │
├──────────────────────────┤
│ [📸 SNAPSHOT] [⚙️ Settings]│
│ [💾 RECORD]  [🔊 Audio]  │
└──────────────────────────┘

Technical Implementation:

• HLS stream via video.js
• Fallback to MJPEG if HLS unavailable
• Reconnect on network interruption
• Tap to fullscreen (potrait + landscape)

4.5 Alerts & Notifications Panel

Screen 5: Alert Details

┌──────────────────────────┐
│ 🔔 ALERTS                │
│ [Filter ▼]               │
├──────────────────────────┤
│ TODAY                    │
│ ┌──────────────────────┐ │
│ │🔴 CRITICAL           │ │
│ │Motion + Intruder      │ │
│ │Deck Camera, 14:32    │ │
│ │[VIEW SNAPSHOT]       │ │
│ │[CALL MARINA] [EMAIL] │ │
│ └──────────────────────┘ │
│                          │
│ ┌──────────────────────┐ │
│ │🟠 WARNING            │ │
│ │Battery Low (43%)     │ │
│ │Salon Camera, 12:15   │ │
│ │[ACKNOWLEDGED]        │ │
│ └──────────────────────┘ │
│                          │
│ ┌──────────────────────┐ │
│ │ℹ️ INFO               │ │
│ │Manual Snapshot       │ │
│ │Deck Camera, 10:45    │ │
│ │User: John Owner      │ │
│ └──────────────────────┘ │
└──────────────────────────┘

Features:

• Color-coded severity (red, orange, blue)
• Context menu for each alert
• Quick actions: "Acknowledge", "Call Marina", "Email Mechanic"
• Filter by severity, date, camera

4.6 Camera Configuration

Screen 6: Camera Settings

┌──────────────────────────┐
│ ⚙️ CAMERA SETTINGS       │
│                          │
│ DECK CAMERA              │
│ Hikvision DS-2CD2043G0-I │
│ ✅ Online, Connected     │
├──────────────────────────┤
│ ⚙️ GENERAL               │
│ • Camera Name            │
│   [Deck Camera (Port)]   │
│ • Location Zone          │
│   [Deck ▼]              │
│ • Recording Enabled      │
│   [Toggle ✓]             │
│                          │
│ 🔔 ALERTS                │
│ • Motion Detection       │
│   [Toggle ✓]             │
│ • Battery Low Alert      │
│   [Toggle ✓]             │
│ • Offline Alert          │
│   [Toggle ✓]             │
│                          │
│ 🤖 AI DETECTION          │
│ • Enable Object Detection│
│   [Toggle ✓]             │
│ • Detection Models       │
│   [YOLOv8-Equipment ▼]   │
│ • Confidence Threshold   │
│   [0.85 ──────●──────1.0]│
│                          │
│ 📊 STATISTICS            │
│ • Uptime: 98%            │
│ • Avg Resolution: 1080p  │
│ • Snapshots (7d): 142    │
│ • Storage Used: 1.2 GB   │
│                          │
│ [🔄 RECONNECT] [🗑️ FORGET]│
└──────────────────────────┘

Configuration Options:

• Enable/disable per-camera
• Adjust alert thresholds
• Select CV models to run
• View statistics + troubleshooting

---

5. Computer Vision Integration Proposal

5.1 Responding to S2-H02 Inventory Detection Request

Integration Approach: Hybrid Manual + Camera-Assisted Detection

The camera system can significantly enhance inventory tracking through computer vision. Rather than replacing manual entry, cameras provide:

1. Auto-Detection of High-Value Items:

   • Tender/Zodiac boats (theft detection)
   • Marine electronics (radar, chartplotter, VHF)
   • Safety equipment (life rafts, flotation devices)
   • Expensive deck equipment (anchors, winches)

2. Confidence-Based Workflow:

   • High confidence (>90%): Auto-populate inventory suggestion
   • Medium confidence (75-90%): Show to user for verification
   • Low confidence (<75%): Flag for manual review

3. Snapshot-to-Inventory Pipeline:

   Camera snapshot received
     ↓ (CV analysis)
   Equipment detected (tender: 94% conf)
     ↓ (exceeds threshold)
   Create inventory suggestion
     ↓ (show to user)
   User reviews + confirms
     ↓ (links to inventory item)
   Snapshot tagged with inventory ID
   

5.2 CV Model Selection

Recommended Model Stack:

Primary: YOLOv8 Custom Fine-Tuning

• Pre-train on COCO dataset (general objects)
• Fine-tune on marine equipment photos
• Target classes:
  • tender (Zodiac, Rib, Dinghy)
  • person (intruder detection)
  • radar_antenna
  • chartplotter
  • solar_panels
  • outboard_motor
  • anchor
  • life_raft
  • vhf_antenna
  • instrument_cluster

Fallback: YOLO-Marine (Open Source)

• Pre-trained specifically for boat equipment
• Ready-to-use, no fine-tuning needed
• Covers basic marine object classes

Optional: Seasonal Anomaly Detection

• Track equipment presence over time
• Alert if tender suddenly missing (theft detection)
• Alert if solar panels covered (weather damage)
• Alert if hatch left open (security/weather risk)

5.3 CV Processing Architecture

Inference Location Options:

Option A: Edge Computing (Recommended for Boats)

Home Assistant Instance
  → YOLOv8 inference (on-device)
  → Send results + snapshot to NaviDocs
  → Benefit: No internet needed for detection
  → Cost: Requires HA instance with GPU (NUC + RTX 4060 ~€500)

Option B: Cloud Processing (Simpler)

Snapshot → NaviDocs
  → Queue to CV worker
  → Run YOLOv8 on backend (GPU instance)
  → Store results in cv_analysis table
  → Benefit: No hardware cost, scalable
  → Cost: Latency (30-60s), internet bandwidth

Option C: Hybrid (Best Balance)

Boat with Home Assistant + GPU NUC:
  → Run YOLOv8 locally (instant results)
  → Send results + snapshot to NaviDocs
  → NaviDocs validates results (optional re-inference)

Boat with Home Assistant only (no GPU):
  → Send snapshot to NaviDocs
  → NaviDocs runs YOLOv8 on backend
  → Return results to app

Recommended Implementation: Hybrid approach

• HA runs YOLOv8 if available (instant)
• NaviDocs re-runs on backend for verification (audit trail)
• Mobile app gets both local + server results

5.4 Inventory Detection Integration

Database Schema Update (extends camera_snapshots):

ALTER TABLE camera_snapshots ADD COLUMN (
  ai_detection_enabled BOOLEAN DEFAULT FALSE,
  detected_equipment TEXT,  -- JSON array of detected items
  equipment_suggestions JSON  -- [{item_class: "tender", confidence: 0.94, inventory_match: "inv-tender-001"}]
);

CREATE TABLE camera_equipment_detections (
  id TEXT PRIMARY KEY,
  snapshot_id TEXT NOT NULL,
  boat_id TEXT NOT NULL,

  -- Detection metadata
  equipment_class TEXT,  -- 'tender', 'radar', 'chartplotter', etc.
  confidence REAL,
  bounding_box JSON,  -- {x, y, width, height} normalized coords

  -- Inventory linking
  suggested_inventory_id TEXT,  -- FK to boat_inventory
  user_confirmed BOOLEAN DEFAULT FALSE,
  confirmed_at DATETIME,
  confirmed_by_user_id TEXT,

  -- Historical tracking
  first_detected DATETIME,
  last_detected DATETIME,
  detection_count INTEGER,  -- How many times seen in photos

  -- Anomaly detection
  is_missing BOOLEAN DEFAULT FALSE,  -- Not seen in last N days
  days_since_last_seen INTEGER,

  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (snapshot_id) REFERENCES camera_snapshots(id),
  FOREIGN KEY (boat_id) REFERENCES entities(id),
  FOREIGN KEY (suggested_inventory_id) REFERENCES boat_inventory(id),
  INDEX idx_boat_class (boat_id, equipment_class, last_detected DESC),
  INDEX idx_missing (boat_id, is_missing)
);

Inventory Suggestion Workflow:

// server/services/cv-analysis.service.js

async function analyzeSnapshotForInventory(snapshotId, boatId) {
  // 1. Run CV inference
  const detections = await runYOLOv8(snapshotId);

  // 2. Filter high-confidence equipment
  const equipmentDetections = detections.filter(
    d => BOAT_EQUIPMENT_CLASSES.includes(d.class) && d.confidence > 0.75
  );

  // 3. Match against existing inventory
  const suggestions = [];
  for (const detection of equipmentDetections) {
    // Find similar items in inventory
    const existingItems = await db.query(
      'SELECT * FROM boat_inventory WHERE boat_id = ? AND category = ?',
      [boatId, detection.class]
    );

    // If no match, create suggestion
    if (existingItems.length === 0) {
      suggestions.push({
        equipment_class: detection.class,
        confidence: detection.confidence,
        bounding_box: detection.bbox,
        action: 'CREATE_NEW_INVENTORY_ITEM'
      });
    } else if (existingItems.length === 1) {
      // Single match - auto-link
      suggestions.push({
        equipment_class: detection.class,
        confidence: detection.confidence,
        suggested_inventory_id: existingItems[0].id,
        action: 'LINK_EXISTING_ITEM'
      });
    } else {
      // Multiple possible matches - ask user
      suggestions.push({
        equipment_class: detection.class,
        confidence: detection.confidence,
        possible_matches: existingItems.map(i => ({id: i.id, name: i.item_name})),
        action: 'USER_CONFIRM_MATCH'
      });
    }
  }

  // 4. Store suggestions
  await db.query(
    'UPDATE camera_snapshots SET equipment_suggestions = ? WHERE id = ?',
    [JSON.stringify(suggestions), snapshotId]
  );

  // 5. Push notification to user (if high confidence)
  const highConfidenceSuggestions = suggestions.filter(s => s.confidence > 0.90);
  if (highConfidenceSuggestions.length > 0) {
    await notificationService.sendPush(boatId, {
      title: 'Equipment Detected',
      body: `Found ${highConfidenceSuggestions.length} item(s) in latest photo`,
      action: 'REVIEW_SUGGESTIONS'
    });
  }
}

Mobile UI for Equipment Suggestions:

┌──────────────────────────┐
│ 🤖 EQUIPMENT DETECTED    │
│                          │
│ We found these items in  │
│ your latest photos:      │
│                          │
│ ☑️ Tender: Zodiac 310    │
│    (94% confident)       │
│    [Link to Existing]    │
│                          │
│ ☑️ Radar Antenna         │
│    (87% confident)       │
│    [Add as New Item]     │
│                          │
│ ☑️ Life Raft (red)       │
│    (78% confident)       │
│    [Confirm] [Skip]      │
│                          │
│ [CONFIRM ALL]            │
└──────────────────────────┘

5.5 Theft & Anomaly Detection

Missing Equipment Alert:

-- Daily job: Check if equipment not detected in past 7 days
SELECT equipment_class, COUNT(*) as detection_count
FROM camera_equipment_detections
WHERE boat_id = 'boat-123'
  AND is_missing = FALSE
  AND last_detected < DATE('now', '-7 days')
GROUP BY equipment_class;

-- For each missing item:
-- 1. Update is_missing = TRUE
-- 2. Send alert: "Tender not detected in 7 days - check boat"
-- 3. Suggest marina inspection

Anomaly Scoring:

# Historical baseline: avg objects detected per snapshot
baseline_objects = 45  # Historical average

# Current snapshot
current_objects = 12

# Anomaly score
anomaly_score = 1 - (current_objects / baseline_objects)  # 0.73 (unusual!)

# Alert if anomaly_score > 0.6 (60% fewer objects than baseline)
if anomaly_score > 0.6:
  send_alert("Unusual activity: boat looks different", severity="warning")

---

6. Security & Rate Limiting

6.1 Webhook Authentication & Validation

HMAC-SHA256 Signature Validation:

// server/routes/webhooks.js

async function validateHomeAssistantWebhook(req, res, next) {
  const signature = req.headers['x-ha-signature'];
  const boatId = req.body.boat_id;

  if (!signature || !boatId) {
    return res.status(401).json({ error: 'Missing signature or boat_id' });
  }

  // 1. Retrieve HA API token from database
  const boat = await db.query('SELECT ha_api_token FROM entities WHERE id = ?', [boatId]);
  if (!boat) {
    return res.status(403).json({ error: 'Boat not found' });
  }

  // 2. Calculate expected signature
  const bodyString = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', boat.ha_api_token)
    .update(bodyString)
    .digest('hex');

  // 3. Constant-time comparison (prevent timing attacks)
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 4. Verify timestamp (prevent replay attacks)
  const eventAge = Date.now() - new Date(req.body.timestamp).getTime();
  const MAX_AGE_MS = 5 * 60 * 1000;  // 5 minutes
  if (eventAge > MAX_AGE_MS) {
    return res.status(400).json({ error: 'Event too old (replay attack?)' });
  }

  next();
}

6.2 Rate Limiting

Per-Endpoint Rate Limits:

// server/config/rate-limits.js

const rateLimits = {
  // Webhook: 100 events/minute per boat (normal HA automation)
  'POST /api/webhooks/events/home-assistant': {
    windowMs: 60 * 1000,
    max: 100,
    keyGenerator: (req) => req.body.boat_id,
    message: 'Too many camera events from this boat'
  },

  // Snapshot gallery: 60 requests/minute per user
  'GET /api/boats/:boat_id/snapshots': {
    windowMs: 60 * 1000,
    max: 60,
    keyGenerator: (req) => req.user.id,
    message: 'Too many gallery requests'
  },

  // Live feed: 10 stream connections/minute per user
  'GET /api/boats/:boat_id/live-feeds': {
    windowMs: 60 * 1000,
    max: 10,
    keyGenerator: (req) => req.user.id,
    message: 'Too many live stream requests'
  },

  // Storage upload: 50 uploads/hour per boat
  'POST /api/boats/:boat_id/snapshots/upload': {
    windowMs: 60 * 60 * 1000,
    max: 50,
    keyGenerator: (req) => req.body.boat_id,
    message: 'Snapshot upload quota exceeded'
  }
};

6.3 Image Delivery Security

S3 Signed URLs (Time-Limited Access):

// server/services/snapshot.service.js

async function getSnapshotUrl(snapshotId, boat_id, expiryMinutes = 10) {
  const snapshot = await db.query(
    'SELECT storage_path FROM camera_snapshots WHERE id = ? AND boat_id = ?',
    [snapshotId, boat_id]
  );

  if (!snapshot) {
    throw new Error('Snapshot not found');
  }

  // Generate signed URL (expires in 10 minutes)
  const url = await s3.getSignedUrl('getObject', {
    Bucket: 'navidocs-snapshots',
    Key: snapshot.storage_path,
    Expires: expiryMinutes * 60
  });

  return url;
}

Benefits:

• S3 validates URL signature before serving
• App never receives permanent URL (can't be shared)
• Expires automatically (default 10 min)
• No token stored in browser history

6.4 Tenant Isolation

Verify boat_id Ownership:

// server/middleware/authorize-boat.js

async function authorizeBoot(req, res, next) {
  const boatId = req.params.boat_id;
  const userId = req.user.id;

  // Check user has permission to this boat
  const permission = await db.query(
    `SELECT * FROM boat_permissions
     WHERE boat_id = ? AND user_id = ? AND permission_level IN ('owner', 'captain', 'viewer')`,
    [boatId, userId]
  );

  if (!permission) {
    return res.status(403).json({ error: 'Access denied to this boat' });
  }

  // Store in context for downstream middleware
  req.boatId = boatId;
  req.boatPermission = permission.permission_level;

  next();
}

Permission Levels:

• owner: Full access (view, configure, delete snapshots)
• captain: View access (gallery, live feeds, alerts)
• viewer: Read-only (gallery, no configuration)

6.5 If.TTT Audit Trail

Every snapshot linked to audit entry:

CREATE TABLE audit_log (
  id TEXT PRIMARY KEY,
  boat_id TEXT NOT NULL,
  entity_type TEXT,  -- 'camera_snapshot', 'alert', 'inventory_suggestion'
  entity_id TEXT,
  action TEXT,  -- 'created', 'viewed', 'linked', 'deleted'
  performed_by TEXT,  -- user_id or 'home-assistant'
  timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
  signature TEXT,  -- Ed25519 signature for tamper detection
  hash TEXT,  -- SHA-256 hash of full event
  FOREIGN KEY (boat_id) REFERENCES entities(id),
  INDEX idx_boat_timestamp (boat_id, timestamp DESC)
);

Signature Generation:

const crypto = require('crypto');
const ed25519 = require('ed25519');

async function signAuditEvent(event, privateKey) {
  const eventString = JSON.stringify(event);
  const hash = crypto.createHash('sha256').update(eventString).digest('hex');
  const signature = ed25519.sign(Buffer.from(eventString), privateKey);

  return {
    ...event,
    hash,
    signature: signature.toString('hex'),
    signature_public_key: privateKey.publicKey
  };
}

---

7. Implementation Roadmap

Week 1: Foundation (Priority)

• Webhook receiver endpoint (POST /api/webhooks/events/home-assistant)
• Snapshot storage schema (database table creation)
• HMAC-SHA256 signature validation
• Rate limiting middleware
• S3 integration for snapshot storage

Week 2: Gallery & UI

• Snapshot gallery API (GET /api/boats/{boat_id}/snapshots)
• Mobile UI screens (gallery, details, viewer)
• Thumbnail generation pipeline
• Filter/sort functionality

Week 3: Live Feeds & Alerts

• Live feed discovery API
• HLS/RTSP proxy implementation
• Alert creation & notification API
• Computer vision integration (YOLOv8)

Week 4: Polish & Optimization

• Auto-cleanup job (30-day retention)
• Anomaly detection (missing equipment alerts)
• Statistics dashboard
• Integration testing with Home Assistant

Post-Launch: Enhancement

• Mobile app offline mode (snapshot caching)
• Custom CV models fine-tuning
• Seasonal anomaly detection
• Encrypted cloud backup

---

8. Dependencies & Integration Points

Depends On:

• S2-H01: Codebase architecture analysis (API patterns)
• S2-H02: Inventory tracking schema (equipment detection linking)
• S2-H10: Architecture synthesis (webhook event bus)

Feeds Into:

• S2-H02: Camera equipment detection suggestions
• S2-H05: Quick actions ("Call Marina" from alert)
• S2-H07: Search integration (snapshots by equipment detected)
• S2-H08: WhatsApp integration ("Show me latest photo")

External Integrations:

• Home Assistant instance (webhook sender)
• S3/cloud storage (snapshot files)
• Mobile app (UI implementation)

---

9. Success Criteria

MVP Launch:

• Webhook receives Home Assistant events (motion, battery, alerts)
• Snapshots stored in S3 with 30-day retention
• Gallery loads 20 snapshots in <2 seconds
• Thumbnail generation completes in <10 seconds
• CV detection identifies tender with >90% confidence
• Rate limiting prevents abuse (100 events/min)
• Signature validation prevents replay attacks
• IF.TTT audit trail logged for every snapshot

User Experience:

• "Is my boat OK?" quick check shows latest snapshot
• Gallery filters work intuitively
• CV suggestions linked to inventory with 1 tap
• Alerts reach user in <30 seconds
• Live feed available for main cabin camera

Security:

• Zero unencrypted snapshots in storage
• All APIs require authentication
• Tenant isolation tested + documented
• Rate limits prevent resource exhaustion
• Signed URLs prevent URL sharing

---

Conclusion

This camera integration system provides boat owners with the peace-of-mind monitoring they need for a critical use case: "Is my boat OK when I'm not there?" By combining Home Assistant's flexibility, real-time webhook events, intelligent computer vision analysis, and mobile-first UI design, NaviDocs becomes indispensable to daily boat ownership.

The hybrid manual + camera-assisted inventory detection approach responds to S2-H02's needs while maintaining simplicity and high confidence levels. The security hardening prevents common webhook attack vectors (replay, signature forgery, rate-based DDoS).

Next: S2-H10 synthesizes all 11 agent specs into a unified technical architecture document.

---

Document Generated: 2025-11-13 Agent: S2-H04 (Haiku) Confidence: 0.92 Token Cost: ~3,500 tokens