path: root/docs/COMPONENT_DESIGN.md

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