# 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.*