diff options
| author | Peter Stone <thepeterstone@gmail.com> | 2026-03-22 23:48:32 +0000 |
|---|---|---|
| committer | Peter Stone <thepeterstone@gmail.com> | 2026-03-22 23:48:32 +0000 |
| commit | f024a6a1cbcb68395fe1a15d4ac852c2be2416e6 (patch) | |
| tree | 149db55dbc69b04a5aa02edf88dbe8a5d83f1841 /docs/COMPONENT_DESIGN.md | |
| parent | 455206121f2061d5bc81b629da7978e1975845d9 (diff) | |
chore: unify and centralize agent configuration in .agent/
Diffstat (limited to 'docs/COMPONENT_DESIGN.md')
| -rw-r--r-- | docs/COMPONENT_DESIGN.md | 997 |
1 files changed, 0 insertions, 997 deletions
diff --git a/docs/COMPONENT_DESIGN.md b/docs/COMPONENT_DESIGN.md deleted file mode 100644 index ba82612..0000000 --- a/docs/COMPONENT_DESIGN.md +++ /dev/null @@ -1,997 +0,0 @@ -# Sailing Companion App — Component Design Document - -**Version:** 1.0 -**Date:** 2026-03-13 -**Status:** Draft - ---- - -## Table of Contents - -1. [Overview & Vision](#1-overview--vision) -2. [Competitive Analysis](#2-competitive-analysis) -3. [Core Technical Components](#3-core-technical-components) -4. [Technical Boating Features](#4-technical-boating-features) -5. [System Architecture](#5-system-architecture) -6. [Data Model Essentials](#6-data-model-essentials) -7. [External Integrations](#7-external-integrations) -8. [UX Principles](#8-ux-principles) -9. [Constraints & Considerations](#9-constraints--considerations) -10. [Phased Roadmap](#10-phased-roadmap) - ---- - -## 1. Overview & Vision - -### Purpose - -A sailing companion app that serves as an integrated bridge instrument, weather advisor, performance coach, and safety system — all in one offline-capable mobile application. It replaces the need to juggle multiple single-purpose apps while underway. - -### Target Users - -| Segment | Use Case | -|----------------------|-------------------------------------------------------------| -| **Daysailors** | Quick weather check, anchor alarm, basic navigation | -| **Coastal cruisers** | Route planning, tide overlays, trip logging, safety alerts | -| **Passage makers** | Offshore weather routing, polar performance, watch keeping | -| **Club racers** | VMG optimization, layline calculation, polar targets | -| **Liveaboards** | Anchor watch, weather monitoring, logbook, maintenance logs | - -### Key Differentiators - -1. **Offline-first architecture** — full charting, routing, and safety features work without connectivity. -2. **Integrated performance polars** — real-time VMG coaching tied directly to weather and routing. -3. **Single-pane-of-glass bridge** — weather, chart, instruments, and safety on one screen. -4. **NMEA integration without proprietary lock-in** — works with any standard instrument bus. -5. **Glance-able UI designed for the cockpit** — large targets, high contrast, wet-hand friendly. - -### Value Proposition - -> "One app, one screen, everything you need from dock to dock — online or off." - -Existing solutions force sailors to switch between a charting app, a weather app, a performance app, and a tide app. This product unifies all four and adds safety features (MOB, anchor alarm, watch alerts) that currently require dedicated hardware or separate apps. - ---- - -## 2. Competitive Analysis - -### Feature Comparison Matrix - -| Feature | Navily | Windy | PredictWind | OpenCPN | SailGrib | Tides (various) | Navico GoFree | **This App** | -|----------------------------------|:------:|:-----:|:-----------:|:-------:|:--------:|:----------------:|:-------------:|:------------:| -| Vector charts | - | - | - | ✓✓ | ✓ | - | ✓✓ | ✓✓ | -| Raster charts | - | - | - | ✓✓ | ✓ | - | ✓ | ✓ | -| Weather overlay (wind/pressure) | - | ✓✓ | ✓✓ | ✓ | ✓✓ | - | ✓ | ✓✓ | -| Tide/current predictions | ✓ | ✓ | ✓ | ✓ | ✓ | ✓✓ | ✓ | ✓✓ | -| Route planning | - | - | ✓✓ | ✓✓ | ✓✓ | - | ✓ | ✓✓ | -| Weather routing (isochrones) | - | - | ✓✓ | ✓* | ✓✓ | - | - | ✓✓ | -| Performance polars | - | - | ✓ | ✓* | ✓ | - | - | ✓✓ | -| NMEA instrument integration | - | - | - | ✓✓ | - | - | ✓✓ | ✓✓ | -| MOB alarm | - | - | - | ✓ | - | - | ✓ | ✓✓ | -| Anchor alarm | ✓ | - | - | ✓* | - | - | ✓ | ✓✓ | -| Offline charts/weather | - | ✓* | ✓* | ✓✓ | ✓✓ | ✓ | ✓ | ✓✓ | -| Trip logbook | ✓ | - | - | ✓* | - | - | - | ✓✓ | -| Mobile-native UI | ✓✓ | ✓✓ | ✓✓ | - | ✓ | ✓✓ | ✓ | ✓✓ | - -✓✓ = strong, ✓ = present, ✓* = via plugin/limited, - = absent - -### Gaps in Existing Solutions - -| Gap | Who suffers | Our answer | -|------------------------------------------------------|----------------------|-----------------------------------------------| -| No single app combines charting + weather + polars | Coastal/offshore | Unified bridge view | -| OpenCPN is powerful but desktop-first | Mobile-only sailors | Native mobile with full OpenCPN-class features| -| Windy/PredictWind lack real-time instrument data | Performance sailors | NMEA integration with live polar overlay | -| Navily focuses on social/anchorages, not navigation | Passage makers | Full nav suite, no social features | -| Tide apps are standalone, not integrated with charts | Coastal cruisers | Tide/current overlays on the chart | -| Anchor alarms require separate apps | All anchoring sailors| Built-in anchor watch with configurable alerts| -| No good offline weather routing on mobile | Offshore sailors | Offline GRIB processing + isochrone routing | - ---- - -## 3. Core Technical Components - -### Component Architecture Overview - -``` -┌──────────────────────────────────────────────────────────────────┐ -│ UI / Presentation │ -│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────────┐ │ -│ │ Chart │ │Instrument│ │ Weather │ │ Safety / Alerts │ │ -│ │ View │ │ Panel │ │ Overlay │ │ Panel │ │ -│ └────┬─────┘ └────┬─────┘ └─────┬─────┘ └───────┬──────────┘ │ -│ │ │ │ │ │ -├───────┴─────────────┴─────────────┴───────────────┴──────────────┤ -│ Application Services │ -│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │ -│ │ Navigation │ │ Weather │ │ Performance│ │ Safety │ │ -│ │ Engine │ │ Service │ │ Tracker │ │ Monitor │ │ -│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └──────┬───────┘ │ -│ │ │ │ │ │ -├────────┴──────────────┴──────────────┴───────────────┴───────────┤ -│ Data Layer │ -│ ┌──────────┐ ┌──────────┐ ┌───────────┐ ┌────────────────┐ │ -│ │ Chart DB │ │ Weather │ │ Logbook │ │ Settings / │ │ -│ │ (S-57/ │ │ Cache │ │ Store │ │ Boat Profile │ │ -│ │ MBTiles)│ │ (GRIB) │ │ (SQLite) │ │ (SQLite) │ │ -│ └─────┬────┘ └────┬─────┘ └─────┬─────┘ └───────┬────────┘ │ -│ │ │ │ │ │ -├────────┴───────────┴─────────────┴───────────────┴───────────────┤ -│ Platform / Hardware │ -│ ┌────────┐ ┌──────────┐ ┌───────────┐ ┌──────────────────┐ │ -│ │ GPS │ │ NMEA │ │ Compass / │ │ Cloud Sync │ │ -│ │ Module │ │ Bridge │ │ Sensors │ │ (optional) │ │ -│ └────────┘ └──────────┘ └───────────┘ └──────────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ -``` - -### 3.1 Navigation & Vector Charting Module - -**Responsibility:** Render nautical charts, manage chart data, handle pan/zoom, and overlay navigation objects (waypoints, routes, tracks, AIS targets). - -| Subcomponent | Technology | Notes | -|----------------------|-----------------------------------|--------------------------------------------| -| Chart renderer | MapLibre GL Native / custom tiles | GPU-accelerated vector rendering | -| Chart data store | MBTiles (SQLite-backed) | Offline-first; predownloaded chart regions | -| S-57/S-63 parser | Custom or libosmium-based | Converts ENC data to internal tile format | -| Symbol library | INT-1 compliant symbol set | IHO S-52 presentation library | -| Overlay engine | Canvas/GL overlay layer | Routes, tracks, AIS, weather, tides | - -**Key behaviors:** -- Seamless zoom from overview to harbor-scale. -- Depth shading with configurable safety contour. -- Chart quilting (multiple chart scales blended). -- Tap-to-query chart objects (buoys, lights, depths). - -### 3.2 Real-time Weather & Environmental Data - -**Responsibility:** Ingest, cache, and visualize wind, pressure, temperature, precipitation, wave, current, and tide data. - -| Data Type | Source(s) | Update Interval | Offline Strategy | -|------------------------|-------------------------------|-----------------|----------------------------| -| Surface wind | GFS/ECMWF via GRIB2 | 6h | Pre-download GRIB files | -| Barometric pressure | GFS, device sensor | 6h / real-time | GRIB + local sensor | -| Tide height | NOAA CO-OPS, UKHO, SHOM | Static harmonic | Harmonic constants on-device| -| Tidal current | NOAA, regional models | Static harmonic | Harmonic constants on-device| -| Sea state / swell | WW3 via GRIB2 | 6h | Pre-download | -| Precipitation / clouds | GFS/ECMWF | 6h | Pre-download | -| Lightning | Blitzortung / provider API | Real-time | Not available offline | - -**GRIB processing pipeline:** - -``` - Download GRIB2 ──► Decode (eccodes) ──► Spatial index ──► Render to tile cache - │ │ - │ ┌──────────────────┐ │ - └──────────────────►│ Interpolation │◄────────────────┘ - │ (bilinear, time) │ - └────────┬─────────┘ - │ - Weather at lat/lon/time -``` - -### 3.3 Sailing Performance Tracking - -**Responsibility:** Compute and display real-time performance metrics derived from GPS, NMEA instruments, and boat polars. - -**Core metrics computed:** - -| Metric | Source(s) | Computation | -|--------|-----------|-------------| -| SOG (Speed Over Ground) | GPS | Direct from GPS fix | -| COG (Course Over Ground) | GPS | Direct from GPS fix | -| BSP (Boat Speed) | NMEA paddlewheel | Direct from instrument | -| HDG (Heading) | NMEA compass / device | Magnetic + variation = True | -| TWS/TWD (True Wind) | AWS/AWA + BSP + HDG | Vector triangle resolution | -| VMG (Velocity Made Good) | TWA + BSP | BSP × cos(TWA) | -| VMC (Velocity Made good to Course) | COG + SOG + bearing to WP | SOG × cos(bearing delta) | -| Heel angle | NMEA or device accelerometer | Direct or computed | -| Leeway | Heel + BSP + boat model | Empirical formula per hull type | -| Current set/drift | SOG/COG vs BSP/HDG | Vector difference | -| Polar % | BSP vs target BSP at TWS/TWA | (BSP / polar_target) × 100 | - -**Polar engine:** -- Stores polar tables as TWS × TWA → target BSP lookup. -- Interpolates between data points (bicubic). -- Computes optimal VMG angles (upwind/downwind) per TWS. -- Outputs target boat speed and target TWA for current conditions. - -### 3.4 Route Planning & Optimization - -**Responsibility:** Create, edit, and optimize sailing routes considering weather, currents, tides, and boat polars. - -**Route planning modes:** - -1. **Manual waypoint routing** — user taps waypoints on chart; system computes distance, bearing, ETAs. -2. **Great-circle / rhumb-line routing** — for offshore passages. -3. **Weather routing (isochrone)** — optimal route given GRIB forecast and boat polars. - -**Isochrone weather routing algorithm:** - -``` - Start ──► Generate fan of headings (5° increments) - │ - ▼ - For each heading, compute BSP from polars at - forecast wind (TWS/TWD) and current - │ - ▼ - Advance position by BSP × Δt (typically 1-3h steps) - │ - ▼ - Prune: remove dominated points (slower to same isochrone) - │ - ▼ - Repeat until isochrone reaches destination - │ - ▼ - Backtrace optimal path through isochrone tree -``` - -**Tide gate logic:** Route optimizer accounts for tidal current vectors at each waypoint leg, adjusting ETAs and optimal departure times. - -### 3.5 Safety & Alerting System - -**Responsibility:** Monitor conditions and trigger alerts for safety-critical events. - -| Alert Type | Trigger | Priority | Action | -|--------------------|------------------------------------------------------|----------|----------------------------------| -| **MOB** | User activation (hardware button / screen button) | CRITICAL | Drop MOB waypoint, start timer, show bearing/distance, sound alarm | -| **Anchor drag** | Position exceeds watch circle radius | HIGH | Audible + visual alarm, log event| -| **Depth** | Depth < user-configured minimum | HIGH | Audible alarm | -| **Off-course** | XTE > user-configured limit | MEDIUM | Visual + optional audible | -| **Weather change** | Wind shift > 30° or gust > threshold | MEDIUM | Push notification | -| **Watch alarm** | Timer expires (configurable intervals) | LOW | Audible alarm | -| **AIS CPA/TCPA** | Closest Point of Approach < threshold | HIGH | Visual + audible alarm | -| **Waypoint arrival**| Distance to active WP < arrival radius | LOW | Notification, auto-advance route | - -**MOB workflow:** -1. Single-tap large MOB button (always visible) → drops waypoint at current GPS position. -2. Screen switches to MOB view: bearing and distance to MOB point, elapsed time. -3. Compass ring shows bearing to MOB. -4. If NMEA autopilot connected: offer "Williamson Turn" or "Direct Return" course command. -5. MOB event logged with timestamp, position, conditions. -6. Cannot be silenced without explicit confirmation. - -### 3.6 Data Persistence & Cloud Sync - -**Local storage (SQLite + file system):** - -| Store | Format | Size Estimate | -|--------------------|--------------|----------------------| -| Chart tiles | MBTiles | 500 MB – 5 GB | -| GRIB weather | GRIB2 files | 50 – 500 MB | -| Tide harmonics | SQLite table | ~10 MB | -| Logbook / tracks | SQLite | ~1 MB/year | -| Boat profiles | SQLite | <1 MB | -| Routes / waypoints | SQLite | <1 MB | -| Settings | SharedPrefs / UserDefaults | <100 KB | - -**Cloud sync strategy:** -- Sync logbook, routes, waypoints, boat profiles, and settings. -- Do NOT sync charts or GRIB data (too large, user downloads per-region). -- Conflict resolution: last-write-wins with device ID tiebreaker; logbook entries are append-only (no conflicts). -- Sync protocol: RESTful API with delta payloads; background sync on connectivity. -- Optional: WebDAV or self-hosted sync for privacy-conscious users. - -### 3.7 Hardware Integration - -**GPS:** -- Primary: device GPS (CoreLocation / Android FusedLocation). -- Secondary: external GPS via NMEA over TCP/UDP, Bluetooth, or USB serial. -- Fix rate: 1 Hz minimum; 5-10 Hz preferred for racing. - -**NMEA 0183/2000 integration:** - -``` - ┌───────────────────┐ ┌──────────────────┐ - │ NMEA Instruments │ │ WiFi/BT NMEA │ - │ (wind, depth, │────────►│ Gateway │ - │ speed, compass) │ wired │ (e.g. Yacht │ - └───────────────────┘ │ Devices, iKonvert│ - │ Digital Yacht) │ - └────────┬─────────┘ - │ TCP/UDP - ▼ - ┌──────────────────────┐ - │ NMEA Parser Module │ - │ ─────────────────── │ - │ $WIMWV → Wind │ - │ $GPGGA → Position │ - │ $HCHDG → Heading │ - │ $SDDBT → Depth │ - │ $VWVHW → Speed │ - │ $GPRMB → Nav info │ - │ !AIVDM → AIS │ - └──────────┬───────────┘ - │ - ▼ - ┌──────────────────────┐ - │ Sensor Fusion │ - │ & Smoothing │ - └──────────────────────┘ -``` - -**Supported NMEA sentences (priority):** - -| Sentence | Data | Priority | -|----------|---------------------|----------| -| GGA/GLL | GPS position | P0 | -| RMC | Position + SOG/COG | P0 | -| MWV | Wind angle/speed | P0 | -| HDG/HDM | Heading | P0 | -| DBT/DPT | Depth | P1 | -| VHW | Boat speed/heading | P1 | -| VDM/VDO | AIS messages | P1 | -| XTE | Cross-track error | P2 | -| MTA/MMB | Air temp / pressure | P2 | -| RSA | Rudder angle | P3 | - -### 3.8 UI Framework & Visualization - -**Rendering stack:** -- **Charts:** MapLibre GL Native (iOS/Android) for GPU-accelerated vector tile rendering. -- **Instruments:** Custom canvas/Skia-rendered gauges (avoid DOM/layout overhead). -- **Weather overlay:** Particle animation (wind flow) + contour fill (pressure) rendered as GL overlay. -- **Performance dials:** Custom circular gauge widgets with polar target arcs. - -**Layout modes:** - -``` -┌─────────────────────────────────────────────┐ -│ NAVIGATION MODE │ -│ ┌─────────────────────────┬──────────────┐ │ -│ │ │ Wind: 15kt │ │ -│ │ │ TWA: 45° │ │ -│ │ CHART VIEW │ BSP: 6.2kt │ │ -│ │ (routes, AIS, tides) │ VMG: 4.4kt │ │ -│ │ │ Depth: 12m │ │ -│ │ │ COG: 225°T │ │ -│ ├─────────────────────────┴──────────────┤ │ -│ │ [MOB] [Anchor] [Route] [Weather] │ │ -│ └────────────────────────────────────────┘ │ -└─────────────────────────────────────────────┘ - -┌─────────────────────────────────────────────┐ -│ INSTRUMENT MODE │ -│ ┌───────────┬───────────┬────────────────┐ │ -│ │ WIND │ COMPASS │ BOAT SPEED │ │ -│ │ ◯ dial │ ◯ rose │ ◯ dial │ │ -│ │ AWS TWS │ HDG COG │ BSP SOG │ │ -│ ├───────────┼───────────┼────────────────┤ │ -│ │ VMG │ DEPTH │ POLAR % │ │ -│ │ 4.4 kt │ 12.3 m │ 94% │ │ -│ ├───────────┴───────────┴────────────────┤ │ -│ │ [MOB] [Anchor] [Route] [Weather] │ │ -│ └────────────────────────────────────────┘ │ -└─────────────────────────────────────────────┘ -``` - -### 3.9 External API Integration Layer - -**Design:** All external data access goes through an integration layer with: -- Retry logic with exponential backoff. -- Response caching with configurable TTL. -- Offline fallback to cached data with staleness indicator. -- Provider abstraction (swap weather sources without touching business logic). - -``` -┌──────────────────────────────────────────┐ -│ API Integration Layer │ -├──────────────────────────────────────────┤ -│ ┌────────────┐ ┌────────────────────┐ │ -│ │ Rate │ │ Cache Manager │ │ -│ │ Limiter │ │ (TTL, staleness) │ │ -│ └──────┬─────┘ └─────────┬──────────┘ │ -│ │ │ │ -│ ┌──────┴──────────────────┴──────────┐ │ -│ │ Provider Adapters │ │ -│ │ ┌──────┐ ┌──────┐ ┌───────────┐ │ │ -│ │ │ NOAA │ │Windy │ │OpenWeather│ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ └──────┘ └──────┘ └───────────┘ │ │ -│ └────────────────────────────────────┘ │ -└──────────────────────────────────────────┘ -``` - ---- - -## 4. Technical Boating Features - -### 4.1 Real-time Wind Visualization and Laylines - -**Wind field rendering:** -- Animated particle flow showing wind direction and relative speed across the chart. -- Color gradient encodes wind speed (Beaufort scale palette). -- Particle density increases with wind strength. - -**Layline computation:** - -``` - WIND (TWD) - │ - │ - ╱ │ ╲ - ╱ TWA │ TWA ╲ - ╱ (opt) │ (opt) ╲ - ╱ │ ╲ - Port layline │ Starboard layline - ╲ │ ╱ - ╲ │ ╱ - ╲ │ ╱ - ╲ │ ╱ - ╲ │ ╱ - ╲ │ ╱ - ╲ │ ╱ - ╲│╱ - MARK / WP -``` - -- Laylines computed from optimal VMG angles at current TWS (from polars). -- Adjusted for current set/drift. -- Displayed as semi-transparent cones on chart overlay. -- Tack/gybe point suggested where layline intersects course to waypoint. - -### 4.2 Tide/Current Predictions and Overlays - -**Tide height display:** -- Tide curve graph for selected station (24h view with current time marker). -- High/low predictions with times. -- Color-coded depth on chart adjusts for tide height relative to chart datum. - -**Tidal current overlay:** -- Animated arrows on chart showing current direction and speed. -- Arrow length/color proportional to current strength. -- Time-scrubbing: user can slide a time bar to see predicted currents at future times. -- Current vectors used in route ETA calculation and weather routing. - -**Computation:** Harmonic analysis using on-device tidal constituent databases (NOAA, UKHO). No network required after initial download. - -### 4.3 Waypoint and Route Management - -**Waypoint properties:** - -| Field | Type | Notes | -|----------------|----------|-------------------------------| -| Name | String | User-editable label | -| Position | LatLon | WGS-84 | -| Symbol | Enum | IHO-compatible icon set | -| Arrival radius | Float(m) | Triggers waypoint arrival | -| Notes | Text | Free-form | -| Created | DateTime | Auto-set | - -**Route features:** -- Ordered waypoint list with per-leg distance, bearing (true/magnetic), and ETA. -- Drag-to-reorder and drag-to-insert intermediate waypoints. -- Route statistics: total distance, estimated time (at configurable speed or from polars + weather). -- Import/export: GPX, KML. -- Reverse route (one tap). - -**Distance/bearing engine:** -- Vincenty inverse formula for accuracy on all distances. -- Rhumb line and great circle options. -- Automatic magnetic variation from WMM (World Magnetic Model) coefficients. - -### 4.4 Boat Performance Metrics - -**Instrument data flow:** - -``` - NMEA / GPS sensors - │ - ▼ - ┌──────────────┐ - │ Raw data │ - │ buffer │ ← 1-10 Hz input - └──────┬───────┘ - │ - ▼ - ┌──────────────┐ - │ Damping & │ ← Configurable: 1s, 3s, 10s, 30s - │ smoothing │ - └──────┬───────┘ - │ - ▼ - ┌──────────────┐ - │ Derived │ ← True wind, VMG, leeway, current, polar % - │ calculations│ - └──────┬───────┘ - │ - ▼ - ┌──────────────┐ - │ UI display │ ← Instruments, chart overlays, alerts - │ + logging │ - └──────────────┘ -``` - -**Damping:** Exponential moving average with user-configurable time constant. Racing mode uses shorter damping; cruising mode uses longer for stability. - -### 4.5 Polar Performance Diagrams - -**Polar diagram display:** - -``` - 0° (head to wind) - │ - │ No-sail zone - 315°──┼──045° - ╱ │ ╲ - ╱ ┌───┼───┐ ╲ - 270° │ │ │ 090° - ╲ │ │ │ ╱ - ╲ └───┼───┘ ╱ - 225°──┼──135° - │ - 180° (dead downwind) - - ── Polar curve at current TWS - -- Target BSP at each TWA - • Current boat position on polar -``` - -**Features:** -- Display polar diagram with target curve for current TWS. -- Interpolate between stored TWS values. -- Show current BSP/TWA as a dot on the polar. -- Highlight optimal VMG angles (upwind and downwind). -- Polar % shown as percentage of target at current TWA. -- Support user-editable polar tables or import from ORC/manufacturer data. - -### 4.6 MOB (Man Overboard) Quick Activation - -- **Activation:** Single tap on persistent on-screen MOB button (minimum 60×60pt touch target, high-contrast red). -- **Immediate actions:** - 1. Record GPS position at moment of activation. - 2. Sound continuous alarm. - 3. Switch display to MOB navigation view. - 4. Start elapsed timer. - 5. Log event to logbook. -- **MOB navigation view:** - - Large bearing arrow pointing to MOB position. - - Distance in meters/feet (auto-scales). - - Elapsed time since MOB. - - Current position and MOB position on chart. - - Wind and current conditions at time of event. -- **Recovery:** Explicit "Recovered" confirmation required to exit MOB mode. - -### 4.7 Anchor Alarm and Watch Circle - -**Configuration:** -- Drop anchor position: auto (GPS at time of set) or manual (tap on chart). -- Watch circle radius: user-configurable (default: calculated from scope × depth + freeboard). -- Alert threshold: distance from anchor position exceeding radius. - -**Monitoring:** -- Continuous GPS monitoring at configurable interval (default: 10s, high-accuracy mode: 1s). -- Displays current swing radius on chart as a circle overlay. -- Historical track shows boat movement around anchor. -- Alert escalation: visual → audible → persistent notification (survives app background/screen lock). - -**Anchor scope calculator:** - -``` - Scope = Chain/Rode Out ÷ (Depth + Freeboard) - - Input: Depth (from sounder or manual), Freeboard (from boat profile) - Recommended: 5:1 chain, 7:1 mixed rode - Watch circle radius = Rode Out × cos(asin((Depth + Freeboard) / Rode Out)) -``` - -### 4.8 Trip Logging and Electronic Logbook - -**Automatic entries (system-generated):** -- Track recording: continuous GPS track at configurable interval (5s – 60s). -- Hourly log: position, SOG, COG, wind, barometer, depth (if available). -- Event log: route activation, waypoint arrival, anchor set/weigh, MOB, alarms. - -**Manual entries:** -- Sail changes, engine on/off, weather observations, crew notes. -- Photo attachment (geo-tagged). - -**Log format:** - -| Time (UTC) | Position | SOG | COG | Wind | Baro | Depth | Event / Notes | -|------------|-----------------|-----|-----|----------|-------|-------|------------------------| -| 08:00 | 41°23.4N 71°12.1W | 6.2 | 225 | 15kt SW | 1018 | 14m | Departed slip | -| 09:00 | 41°18.7N 71°08.3W | 5.8 | 210 | 18kt SW | 1017 | 22m | Full main + jib | -| 09:15 | 41°17.2N 71°07.1W | 6.5 | 195 | 20kt SW | 1016 | 28m | Reef #1 main | - -**Export:** CSV, GPX (track), PDF (formatted logbook page). - -### 4.9 True/Magnetic Heading Conversion - -- World Magnetic Model (WMM) coefficients stored on-device (updated annually). -- Auto-compute magnetic variation for any position and date. -- All headings displayed with user preference: True (°T), Magnetic (°M), or both. -- Compass rose on chart rotates to show magnetic north offset. -- All NMEA headings tagged as magnetic are auto-converted using local variation. - -### 4.10 Night Vision Mode - -- Single-tap toggle from any screen. -- Color scheme: red-on-black (preserves night adaptation). -- All chart colors remapped to red spectrum. -- Screen brightness reduced (app-controlled dimming below OS minimum). -- Instrument displays switch to red numerals on black background. -- No white flashes from notifications or overlays. -- Chart light symbols (Fl, Iso, Oc, etc.) rendered with visible flash patterns on dark background. - ---- - -## 5. System Architecture - -### 5.1 Platform Stack - -| Layer | Technology | -|---------------|------------------------------------------------------| -| Mobile UI | Kotlin Multiplatform (Android) + Swift (iOS) | -| Chart engine | MapLibre GL Native (shared C++ core) | -| Local DB | SQLite (via SQLDelight / GRDB) | -| Chart storage | MBTiles (SQLite-backed tile packages) | -| Weather | Custom GRIB2 decoder (Rust/C FFI for performance) | -| Networking | Ktor (KMP) / URLSession (iOS) | -| Background | WorkManager (Android) / BGTaskScheduler (iOS) | -| Web (future) | Kotlin/JS or separate PWA consuming same API layer | - -**Rationale:** Native per-platform for performance-critical operations (chart rendering, GRIB decoding, GPS). Shared business logic via Kotlin Multiplatform where feasible. - -### 5.2 Backend Services - -``` -┌──────────────────────────────────────────────┐ -│ Cloud Backend │ -│ ┌──────────────┐ ┌──────────────────────┐ │ -│ │ Auth / User │ │ Sync API │ │ -│ │ Service │ │ (routes, logs, prefs)│ │ -│ └──────────────┘ └──────────────────────┘ │ -│ ┌──────────────┐ ┌──────────────────────┐ │ -│ │ Chart Index │ │ Weather Proxy / │ │ -│ │ & Download │ │ GRIB Distribution │ │ -│ └──────────────┘ └──────────────────────┘ │ -│ ┌──────────────────────────────────────┐ │ -│ │ Push Notification Service │ │ -│ └──────────────────────────────────────┘ │ -└──────────────────────────────────────────────┘ -``` - -- **Auth:** OAuth 2.0 / email+password. Optional — app is fully functional without account. -- **Sync API:** REST with JSON delta payloads. Supports offline queue with conflict resolution. -- **Chart index:** Catalog of available chart regions with version metadata. Client downloads tiles directly (CDN-backed). -- **Weather proxy:** Aggregates GRIB data from multiple sources; serves cropped/subsetted GRIB files for requested regions to minimize bandwidth. -- **Push notifications:** Weather alerts, anchor drag (if device loses connectivity, companion device can alert). - -### 5.3 Offline-First Data Model - -**Principle:** Every core feature works without connectivity. Online access enhances but never gates functionality. - -| Feature | Offline capability | Online enhancement | -|----------------------|--------------------------------------------------------|-------------------------------------| -| Chart display | Pre-downloaded chart tiles | On-demand tile streaming | -| Navigation | Full waypoint/route with GPS | — | -| Weather | Last downloaded GRIB (with staleness warning) | Fresh GRIB download | -| Tides | Full harmonic prediction (no network needed) | — | -| Performance | Full (all computation is local) | — | -| Safety (MOB, anchor) | Full (GPS-only) | — | -| Logbook | Full recording; sync queued for later | Real-time cloud backup | -| AIS | Via NMEA hardware receiver | Internet AIS feed | - -### 5.4 Hardware Sensor Integration Strategy - -**Abstraction layer:** `SensorProvider` interface with implementations for: -1. Device GPS (built-in). -2. Device compass/accelerometer (built-in). -3. NMEA TCP/UDP (WiFi multiplexer — e.g., Yacht Devices, Vesper, Digital Yacht). -4. NMEA Bluetooth (Bluetooth serial adapters). -5. Signal K (JSON-based open marine data protocol over WebSocket). - -**Priority / fallback chain:** -``` -NMEA instrument data (highest precision) - └─► Signal K server - └─► Device built-in sensors (GPS, compass, barometer) - └─► Manual entry / last known (lowest priority) -``` - -**Sensor fusion:** When multiple sources provide the same data (e.g., GPS from device + NMEA), use highest-priority source with automatic fallback on signal loss. - -### 5.5 Cloud Synchronization Approach - -``` - Device A (phone) Cloud Device B (tablet) - ┌──────────────┐ ┌──────────┐ ┌──────────────┐ - │ Local SQLite │──── push ──────►│ Sync API │◄─── push ───│ Local SQLite │ - │ │◄─── pull ───────│ │──── pull ───►│ │ - └──────────────┘ └──────────┘ └──────────────┘ -``` - -- **Sync granularity:** Per-entity (route, waypoint, log entry, setting). -- **Conflict strategy:** Last-write-wins using monotonic device clocks + server timestamp. -- **Append-only entities:** Logbook entries, track points — no conflicts possible. -- **Queue:** Offline changes queued in local `sync_outbox` table; drained on connectivity. -- **Bandwidth budget:** Sync payloads are JSON deltas — typically < 10 KB per sync cycle. - ---- - -## 6. Data Model Essentials - -### 6.1 Key Entities - -``` -┌─────────────┐ ┌──────────────┐ ┌───────────────┐ -│ Route │1────*│ Waypoint │ │ BoatProfile │ -├─────────────┤ ├──────────────┤ ├───────────────┤ -│ id │ │ id │ │ id │ -│ name │ │ route_id(FK) │ │ name │ -│ created_at │ │ seq_order │ │ hull_type │ -│ updated_at │ │ lat │ │ loa │ -│ total_dist │ │ lon │ │ beam │ -│ notes │ │ name │ │ draft │ -└─────────────┘ │ arrival_rad │ │ displacement │ - │ symbol │ │ freeboard │ - │ notes │ │ polar_data │ - └──────────────┘ └───────────────┘ - -┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ -│ BoatPosition │ │ WeatherData │ │ PerformanceLog │ -├──────────────────┤ ├──────────────────┤ ├──────────────────┤ -│ id │ │ id │ │ id │ -│ timestamp │ │ timestamp │ │ timestamp │ -│ lat │ │ lat │ │ position_id(FK) │ -│ lon │ │ lon │ │ bsp │ -│ sog │ │ tws │ │ vmg │ -│ cog │ │ twd │ │ polar_pct │ -│ hdg_true │ │ pressure_hpa │ │ heel_deg │ -│ hdg_mag │ │ wave_height_m │ │ leeway_deg │ -│ depth_m │ │ wave_period_s │ │ current_set │ -│ source (enum) │ │ wave_dir │ │ current_drift │ -│ fix_quality │ │ temp_c │ │ twa │ -└──────────────────┘ │ source (enum) │ │ tws │ - │ model_run │ │ aws │ - └──────────────────┘ │ awa │ - └──────────────────┘ - -┌──────────────────┐ ┌──────────────────┐ -│ LogEntry │ │ AnchorWatch │ -├──────────────────┤ ├──────────────────┤ -│ id │ │ id │ -│ trip_id(FK) │ │ anchor_lat │ -│ timestamp │ │ anchor_lon │ -│ position_id(FK) │ │ radius_m │ -│ type (enum) │ │ set_time │ -│ text │ │ depth_at_set │ -│ auto_generated │ │ rode_out_m │ -│ photo_path │ │ active │ -└──────────────────┘ └──────────────────┘ -``` - -### 6.2 Real-time Streaming vs Historical Storage - -| Data Class | Real-time Buffer | Historical Storage | -|-------------------|-------------------------------------|-------------------------------------------| -| GPS position | Ring buffer, last 60s at full rate | Downsampled to 5s–60s intervals in SQLite | -| Instrument data | Ring buffer, last 60s | Hourly averages in PerformanceLog | -| Weather grid | In-memory GRIB slice for current t | Full GRIB files on disk (last 3 downloads)| -| AIS targets | In-memory map (MMSI → last report) | Not stored (ephemeral) | -| Tide predictions | Computed on-demand | Harmonic constants are static reference | - -### 6.3 Data Freshness and Caching Strategy - -| Data | TTL / Freshness Rule | Staleness Indicator | -|--------------------|--------------------------------------------------------|----------------------------------| -| GRIB weather | Valid until model run + forecast hour; stale after | Yellow "outdated" badge on chart | -| Tide harmonics | Valid for calendar year (annual coefficient update) | — | -| Chart tiles | Valid until chart edition update (check weekly) | "Update available" on chart menu | -| AIS positions | Stale after 5 min (class A) / 30 min (class B) | Target fades on chart | -| GPS fix | Stale after 10s (lost fix) | Red "No GPS" warning bar | -| NMEA instruments | Stale after 5s (no data) | Dashes (--) replace values | - ---- - -## 7. External Integrations - -### 7.1 Weather APIs - -| Provider | Data | Format | Cost Model | Notes | -|----------------|-------------------------|--------|--------------------|---------------------------------| -| NOAA (GFS) | Global wind, pressure | GRIB2 | Free | 0.25° resolution, 6h updates | -| ECMWF (open) | Global wind, pressure | GRIB2 | Free (open data) | 0.1° resolution, 6h updates | -| Windy API | Multi-model access | JSON | Paid (per request) | Good fallback, easy integration| -| OpenWeather | Point forecasts | JSON | Freemium | Useful for simple point lookups| -| NOAA NDBC | Buoy observations | Text | Free | Real-time buoy data | - -**Strategy:** Primary: NOAA GFS (free, GRIB2). Secondary: ECMWF open data. Fallback: Windy API for regions with poor GFS coverage. - -### 7.2 Chart Data Sources - -| Source | Coverage | Format | License | -|---------------------|-----------------|--------------|------------------| -| NOAA ENC | US waters | S-57 | Public domain | -| OpenSeaMap | Global | Vector tiles | ODbL | -| Navionics (license) | Global | Proprietary | Commercial | -| LINZ | New Zealand | S-57 | CC BY 4.0 | -| BSH | Germany | S-57 | Government | - -**Strategy:** Ship with NOAA ENC + OpenSeaMap. Offer Navionics integration as premium add-on. - -### 7.3 AIS Feeds - -- **Hardware:** NMEA-connected AIS receiver (preferred — works offline). -- **Internet:** AIS APIs (MarineTraffic, AISHub) for supplemental coverage when online. -- **Display:** AIS targets rendered on chart with MMSI, vessel name, SOG/COG vector, CPA/TCPA. - -### 7.4 GPS / NMEA Protocols - -| Protocol | Transport | Use Case | -|--------------|------------------|-------------------------------------------| -| NMEA 0183 | TCP/UDP/serial | Legacy instruments (most common) | -| NMEA 2000 | CAN bus → gateway| Modern instrument buses | -| Signal K | WebSocket (JSON) | Open-source boat data server | -| GPX import | File | Route/waypoint exchange | - ---- - -## 8. UX Principles - -### 8.1 Glance-able Critical Information - -- **Primary data** (SOG, COG, depth, wind) visible without any interaction. -- **Font sizing:** minimum 24pt for primary values; 18pt for secondary. -- **Color coding:** depth alarm = red, normal = green/white, stale data = yellow. -- **No modals during navigation** — all alerts are non-blocking banners (except MOB). - -### 8.2 Minimal Taps While Underway - -| Action | Max taps | Notes | -|----------------------------|----------|--------------------------------------| -| View current conditions | 0 | Always visible | -| Activate MOB | 1 | Persistent button | -| Set anchor alarm | 2 | Long-press position → set radius | -| Check next waypoint | 0 | Shown in nav bar | -| Switch day/night mode | 1 | Toggle button | -| View tide at current pos | 1 | Tap tide icon | -| Log a note | 2 | Quick-entry with voice option | - -### 8.3 High-Contrast Readability - -- **Day mode:** Dark text on light background; chart uses standard ECDIS color scheme. -- **Dusk mode:** Reduced brightness, muted colors. -- **Night mode:** Red on black, no blue/white light sources. -- **Sunlight testing:** All UI elements must pass WCAG AAA contrast ratio (7:1) in day mode. - -### 8.4 Touch Optimization for Wet/Gloved Hands - -- Minimum touch target: 60×60pt (larger than standard 44pt). -- Generous spacing between interactive elements (minimum 16pt gap). -- No swipe-only gestures for critical functions — always provide tap alternative. -- Support for hardware buttons (volume keys) as configurable shortcuts (e.g., MOB, mark waypoint). -- Edge gestures disabled in navigation mode to prevent accidental OS navigation. - ---- - -## 9. Constraints & Considerations - -### 9.1 Bandwidth & Connectivity - -| Scenario | Expected bandwidth | Strategy | -|-------------------|--------------------|-----------------------------------------------| -| Harbor WiFi | 1-10 Mbps | Bulk download charts, GRIB, updates | -| Coastal cellular | 100 Kbps – 5 Mbps | Incremental GRIB, sync, AIS feed | -| Offshore (none) | 0 | Full offline; queue sync for later | -| Satellite (Iridium)| 2.4 Kbps | Text-only weather (GRIB subset), position reports| - -**GRIB bandwidth optimization:** -- Request only needed parameters (wind, pressure — skip temperature, clouds if not needed). -- Crop to planned route corridor + 200nm buffer. -- Typical offshore GRIB: 200 KB – 2 MB (manageable on satellite with patience). - -### 9.2 Battery Life - -**Target:** 24+ hours of continuous navigation on a full charge (modern smartphone). - -| Optimization | Impact | -|-------------------------------------------|-----------| -| GPS polling rate: 1 Hz normal, 5 Hz race | High | -| Screen brightness: user-controlled dimming| High | -| Chart rendering: cache rendered tiles | Medium | -| GRIB decode: on-demand, not continuous | Medium | -| Network: batch requests, no polling | Medium | -| Background: limit to anchor alarm + track | Low-Med | - -**Power modes:** -- **Full:** All features active. ~6-8h screen-on. -- **Economy:** Reduced GPS rate (0.2 Hz), no weather animation, dimmed screen. ~16-24h. -- **Anchor watch:** Screen off, GPS at 0.1 Hz, wake on alarm. ~48-72h. - -### 9.3 Screen Visibility - -- Support for both OLED and LCD displays. -- Day mode uses maximum contrast; no subtle gradients. -- Night mode: pure black background (#000000) on OLED saves power and reduces glare. -- Anti-glare: avoid white backgrounds that reflect sunlight; prefer dark/medium chart backgrounds. -- User-adjustable brightness independent of OS brightness. - -### 9.4 Reliability & Safety-Critical Fail-Safes - -- **No single point of failure for position:** Device GPS + optional external GPS. -- **MOB button always accessible:** Rendered above all other UI layers; not dismissible. -- **Anchor alarm survives:** app background, screen lock, low-battery mode, OS memory pressure. -- **Watchdog:** Background process monitors GPS feed; alerts if fix lost for > 30s while underway. -- **Data integrity:** SQLite WAL mode; logbook writes are atomic. -- **Disclaimer:** App is an aid to navigation, not a replacement for proper seamanship, paper charts, and official publications. Displayed prominently at first launch and in About screen. - -### 9.5 Data Privacy & Local Storage - -- **Default local:** All data stored on device. Cloud sync is opt-in. -- **No telemetry of position data** without explicit consent. -- **Track data:** Stays on device unless user explicitly exports or syncs. -- **Account optional:** App is fully functional without creating an account. -- **Self-host option:** Publish sync server specification so users can run their own. -- **Data export:** Users can export all their data (routes, logs, tracks) at any time in open formats (GPX, CSV, JSON). - ---- - -## 10. Phased Roadmap - -### Phase 1 — Foundation (Months 1–4) - -| Deliverable | Priority | -|------------------------------------|----------| -| Chart display (NOAA ENC + OpenSeaMap) | P0 | -| GPS navigation (position, SOG, COG) | P0 | -| Waypoint & route management | P0 | -| Basic instrument display | P0 | -| MOB alarm | P0 | -| Anchor alarm | P0 | -| Day/night mode | P1 | -| GPX import/export | P1 | - -### Phase 2 — Weather & Tides (Months 5–7) - -| Deliverable | Priority | -|--------------------------------------|----------| -| GRIB weather download & display | P0 | -| Wind overlay on chart | P0 | -| Tide predictions (harmonic) | P0 | -| Tidal current overlay | P1 | -| Barometric pressure trend | P1 | -| Offline GRIB storage & staleness | P0 | - -### Phase 3 — Performance & Routing (Months 8–10) - -| Deliverable | Priority | -|--------------------------------------|----------| -| NMEA 0183 integration (TCP/UDP) | P0 | -| True wind calculation | P0 | -| Polar diagram display | P0 | -| VMG / polar % instruments | P0 | -| Layline rendering | P1 | -| Isochrone weather routing | P1 | -| Signal K integration | P2 | - -### Phase 4 — Logbook & Polish (Months 11–13) - -| Deliverable | Priority | -|--------------------------------------|----------| -| Trip logbook (auto + manual) | P0 | -| Track recording & playback | P0 | -| Cloud sync (opt-in) | P1 | -| AIS display (hardware + internet) | P1 | -| CPA/TCPA alerts | P1 | -| PDF logbook export | P2 | -| Compass/heading instrument | P0 | - -### Phase 5 — Advanced & Optimization (Months 14+) - -| Deliverable | Priority | -|--------------------------------------|----------| -| NMEA 2000 via gateway | P1 | -| Navionics chart integration | P2 | -| Satellite weather (Iridium GRIB) | P2 | -| Apple Watch / Wear OS companion | P2 | -| Web dashboard (trip review) | P3 | -| Voice commands for logbook entries | P3 | -| Battery economy mode | P1 | - ---- - -*This document focuses exclusively on sailing/navigation technical features. Social features (crew networking, race communities, marina reviews) are explicitly out of scope.* |