diff options
| author | Claudomator Agent <agent@claudomator> | 2026-03-13 05:57:45 +0000 |
|---|---|---|
| committer | Claudomator Agent <agent@claudomator> | 2026-03-13 05:57:45 +0000 |
| commit | 0b3fc43df0f522a9d2b308c79b35870e3afb08db (patch) | |
| tree | 1a139db9ae59d1038daa42a9a3c93258904ce6df /docs/COMPONENT_DESIGN.md | |
| parent | 1541a823312a55cb42625265d08ea77f92c0f926 (diff) | |
docs: add comprehensive sailing companion app component design
Covers navigation/charting, weather, performance tracking, route
optimization, safety systems, data model, integrations, UX principles,
constraints, and phased roadmap. Excludes social features per spec.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Diffstat (limited to 'docs/COMPONENT_DESIGN.md')
| -rw-r--r-- | docs/COMPONENT_DESIGN.md | 997 |
1 files changed, 997 insertions, 0 deletions
diff --git a/docs/COMPONENT_DESIGN.md b/docs/COMPONENT_DESIGN.md new file mode 100644 index 0000000..ba82612 --- /dev/null +++ b/docs/COMPONENT_DESIGN.md @@ -0,0 +1,997 @@ +# 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.* |