# Field Observer: Realtime Phone Photo & Video Sharing ## What It Is A browser-based app where multiple phones in the field can capture or upload photos and short videos, and every connected peer sees them appear in realtime. No app install required: open a URL, join a group, start sharing. Built on the acequia.io peer-to-peer framework, so media flows directly between phones via WebRTC data channels, with WebDAV as persistent storage and fallback relay. ## Core User Flows ### Flow 1: Capture and share 1. Open URL on phone browser (e.g. `https://geo.camera/apps/field-observer/`) 2. Join or create a group (room code, QR code, or shared link) 3. Capture photo or short video using the device camera (via `getUserMedia`) 4. Media appears instantly on all connected peers' screens ### Flow 2: Upload from camera roll 1. Tap "Upload" button (uses ``) 2. Pick one or more photos/videos from the phone's gallery 3. Thumbnails generate locally, metadata extracted (EXIF GPS, date) 4. Shared to group same as captured media ### Flow 3: Browse history 1. Join an existing group 2. Feed loads from WebDAV manifest (all previously shared media) 3. Scroll, filter by author or date, tap to view full-res 4. For long videos, scrub to any point (byte-range seeking) ## Why Acequia The acequia framework already provides every building block: | Need | Acequia Primitive | |------|-------------------| | Peer discovery | Group + Discovery server (WebSocket) | | Realtime media delivery | WebRTC data channels (`dataBig()` for chunked transfer) | | Shared feed state | Group Shared State (peer-elected leader, shallow merge) | | "New photo" notifications | Event Bus (topic: `media/new`, `media/delete`) | | Persistent storage | WebDAV PUT to `/{group}/media/` | | Auth | JWT three-mode system (device identity, no signup required) | | Offline support | Service worker cache + OPFS local storage | ## Architecture Overview ``` ┌──────────────────────────────────────────────────┐ │ Phone Browser A │ │ ┌────────────┐ ┌──────────┐ ┌──────────────┐ │ │ │ Camera UI │→ │ Encoder │→ │ Share Engine │ │ │ │ getUserMedia│ │ canvas │ │ WebRTC send │ │ │ │ -- or -- │ │ thumbnail│ │ WebDAV PUT │ │ │ │ File picker│ │ EXIF read│ │ OPFS cache │ │ │ └────────────┘ └──────────┘ └──────┬───────┘ │ │ │ │ │ ┌────────────────────────────────────┘ │ │ │ Feed UI (grid of thumbnails + lightbox) │ │ │ Map view (geo-tagged markers) │ │ └───────────────────────────────────────────────│ └──────────────────────────────┬───────────────────┘ │ WebRTC data channel │ (+ WS fallback) ┌──────────────────────────────┴───────────────────┐ │ Phone Browser B │ │ (same components, bidirectional) │ │ OPFS mirror ← replicates media for availability │ └──────────────────────────────────────────────────┘ │ │ WebDAV PUT (persistent copy) ▼ ┌──────────────────────────┐ │ WebDAV Server │ │ /{group}/media/ │ │ /{group}/manifest.json │ │ /{group}/index.json │ ← byte-offset index for long videos └──────────────────────────┘ ``` ## Key Design Decisions ### 1. Capture OR upload, user's choice Two input paths: - **Capture:** `getUserMedia` + `` for photos, `MediaRecorder` for video - **Upload:** `` for existing camera roll items (supports `multiple` for batch upload) Both paths converge at the same point: generate thumbnail, extract metadata, feed into share engine. ### 2. OPFS for local media storage The Origin Private File System replaces IndexedDB for all binary data: - **No serialization overhead**: files are stored as-is, not wrapped in structured clone - **Synchronous access in workers**: `createSyncAccessHandle()` for fast reads in service worker - **No blob size limits**: IndexedDB chokes on large video files in some browsers - **Natural file hierarchy**: mirrors the WebDAV path structure locally Layout in OPFS: ``` /field-observer/{groupId}/ thumb/{mediaId}.jpg full/{mediaId}.jpg clip/{mediaId}.webm ``` IndexedDB is still used for the small metadata index (manifest entries, peer state, settings) where query-by-key is useful. ### 3. Thumbnail-first, full-res on demand When media is captured or uploaded: - Generate a 400px thumbnail on-canvas (fast, small) - Send thumbnail to all peers via WebRTC event bus immediately (~20-50KB) - Write full-res to OPFS immediately (local) - Upload full-res to WebDAV in background - Peers fetch full-res from WebDAV (or via WebRTC route) when tapped ### 4. Feed as shared state The media feed is a shared JSON manifest managed by Group Shared State: ```json { "media": { "cuid123": { "type": "photo", "author": "deviceId-abc", "authorName": "Steph", "timestamp": 1711300000, "location": { "lat": 35.88, "lon": -106.30, "alt": 2100 }, "size": 2456789, "duration": null, "thumbUrl": "/acq/geo.camera/field-observer/{group}/thumb/cuid123.jpg", "fullUrl": "/acq/geo.camera/field-observer/{group}/full/cuid123.jpg", "caption": "" } } } ``` ### 5. Multi-device backup for availability Any peer can opt in as a **mirror**. Mirrors replicate media they receive into their own OPFS and can serve it to other peers via WebRTC routes. This means: - If the original author goes offline, mirrors can still serve the full-res file - If WebDAV is unreachable, the mesh of mirrors keeps media available - Mirrors advertise what they have via shared state (`mirrors` field per media entry) - Replication is opportunistic: mirrors pull full-res in background when on WiFi ```json { "cuid123": { "mirrors": ["deviceId-abc", "deviceId-def", "deviceId-ghi"], "webdav": true } } ``` Fetch priority: OPFS local > WebRTC from nearest mirror > WebDAV server. ### 6. Byte-offset seeking for long videos Long videos (>30s) need random access without downloading the entire file. Two mechanisms: **Server-side (WebDAV):** Standard HTTP Range requests. WebDAV servers support `Range: bytes=START-END` headers natively. The browser's `