diff --git a/.planning/research/ARCHITECTURE.md b/.planning/research/ARCHITECTURE.md new file mode 100644 index 0000000..6d0c759 --- /dev/null +++ b/.planning/research/ARCHITECTURE.md @@ -0,0 +1,89 @@ +# Architecture Research + +**Domain:** Offline-first PWA Architecture +**Researched:** 2026-05-26 +**Confidence:** HIGH + +## Component Architecture + +Since this is a client-side only PWA, the entire architecture runs in the user's browser sandbox. The structure is separated into UI Components, Services (business logic), and Storage. + +``` +┌────────────────────────────────────────────────────────┐ +│ User Interface │ +│ ┌──────────────┐ ┌────────────────┐ ┌──────────────┐ │ +│ │ Stammdaten │ │ Logbook Entry │ │ Settings/ │ │ +│ │ (Forms, Crew)│ │ (Forms, List) │ │ Language │ │ +│ └──────┬───────┘ └───────┬────────┘ └──────┬───────┘ │ +└─────────┼─────────────────┼─────────────────┼──────────┘ + │ │ │ +┌─────────▼─────────────────▼─────────────────▼──────────┐ +│ Application Services │ +│ ┌────────────────┐ ┌────────────────┐ ┌────────────┐ │ +│ │ Geolocation │ │ Weather Service│ │ Export │ │ +│ │ Service (GPS) │ │ (OpenWeather) │ │ Service │ │ +│ └──────┬─────────┘ └───────┬────────┘ └────┬───────┘ │ +└─────────┼───────────────────┼───────────────┼──────────┘ + │ │ │ +┌─────────▼───────────────────▼───────────────▼──────────┐ +│ Data Infrastructure │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ IndexedDB / Dexie.js (Data Persistence) │ │ +│ └──────────────────────────────────────────────────┘ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ Service Worker (Asset Cache & Offline) │ │ +│ └──────────────────────────────────────────────────┘ │ +└────────────────────────────────────────────────────────┘ +``` + +### 1. UI Layer +- **Responsive Layout Shell**: Single page app with a bottom navigation bar for mobile feel and sidebar for tablet/desktop. Responsive and adaptive depending on device size. +- **Form Views**: + - **Stammdaten Form**: Single tabbed view separating Boat Profile, Crew profiles, and the Deviation Table. + - **Logbook List**: Chronological display of journal entries with details and summaries. + - **Logbook Entry Form**: Interactive form with sub-sections for Nautical logs, Weather inputs, Sails, Course, and Consumption controls. +- **Adaptive UI Handler**: Standard CSS variables and OS-detection class selectors (`.platform-ios`, `.platform-android`) to render inputs and dialogs matching Cupertino or Material styles. + +### 2. Services Layer +- **GPS Service**: Interface to browser Geolocation API (`navigator.geolocation`). Provides DMS (Degrees, Minutes, Seconds) coordinate formatting. +- **Weather Service**: Performs asynchronous REST requests to OpenWeatherMap API using coordinates. Handles offline fallback gracefully. +- **Export Service**: Generates a CSV file using standard RFC 4180 parameters, creates a dynamic Blob URL, and triggers browser download or invokes `navigator.share` (Web Share API) for native email/message share. +- **Translation Service**: standard `i18next` engine. Automatically detects system locale on first start (`navigator.language`), falls back to English, and persists user selection in LocalStorage. + +### 3. Data Infrastructure +- **IndexedDB Storage Scheme (Dexie.js)**: + - Table `yacht`: Single record containing vessel specs. + - Table `crew`: Skipper + Crew members. + - Table `deviation`: 37 records mapping `heading` (MgK 0-360) to `deviation` (Abl). + - Table `entries`: Logbook records containing dates, coordinates, courses, weather, sails, and daily consumption. +- **Offline Shell**: Service Worker configured using Workbox via `vite-plugin-pwa`. Caches CSS, JS, HTML, fonts, and icons for immediate load. + +## Data Flow + +### 1. Fetching GPS & Weather +1. User clicks "Auto-Fill GPS/Weather" on a new log entry. +2. Geolocation Service queries `navigator.geolocation.getCurrentPosition()`. +3. Coordinates are returned and set in form state. +4. If internet is available, Weather Service requests OpenWeatherMap using the coordinates. +5. API response (pressure, wind strength, direction, weather icons) is parsed and merged into the form state. +6. User reviews the pre-filled fields and saves the entry. + +### 2. Saving to Database & Local Cache +1. Form state triggers `dexie` write operation: `db.entries.add(formData)`. +2. IndexedDB saves the record locally. +3. The UI queries IndexedDB reactively using `useLiveQuery` from `dexie-react-hooks`, updating lists instantly. +4. No network requests are made, ensuring zero lag. + +## Suggested Build Order + +1. **Setup & PWA Shell**: Initialize Vite React TS, configure `vite-plugin-pwa` with service worker, and setup simple landing shell. +2. **Database Layer**: Implement Dexie.js database schemas, collections, and mock data. +3. **Master Data View (Stammdaten)**: Implement boat profile form, crew cards, and the Deviation grid. +4. **Logbook Entry Forms**: Build the main log entry form, course inputs, and consumption controller. +5. **GPS & Weather Integrations**: Implement device Geolocation fetching and OpenWeatherMap query helpers. +6. **Data Export & Language Switcher**: Add CSV generation/sharing and `react-i18next` localization. +7. **Adaptive UI Polish**: Apply iOS/Android CSS themes and polish responsiveness. + +--- +*Architecture research for: Kapteins Daagbox PWA* +*Researched: 2026-05-26* diff --git a/.planning/research/FEATURES.md b/.planning/research/FEATURES.md new file mode 100644 index 0000000..5ab9bdf --- /dev/null +++ b/.planning/research/FEATURES.md @@ -0,0 +1,61 @@ +# Features Research + +**Domain:** Maritime Ship's Logbook PWA +**Researched:** 2026-05-26 +**Confidence:** HIGH + +## Feature Categories + +### 1. Vessel & Crew Master Data (Stammdaten) +- **Vessel Profile**: Capture Yachtname, Heimathafen, Charterfirma, Eigner, Kennzeichen/Zulassungsnummer, Funk-Rufzeichen, ATIS-Nr, MMSI-Nr. +- **Crew Registry**: Skipper and crew profiles (up to 6 members) with Name, Anschrift, Geburtstag, Tel-Nr, Nationalität, Pass-Nr, Blutgruppe, Allergien, Krankheiten. +- **Deviation Table (Steuertafel)**: Standard magnetic compass deviation table mapping Compass Heading (MgK) from 000° to 360° (in 10° increments) to Deviation (Ablenkung). + +### 2. Journey Logbook (Logbucheintrag) +- **General Journey Info**: Date, Day of Travel (. Reisetag), Departure (Reise von) & Destination (nach). +- **Hourly/Event Entry**: Time, Compass Course (MgK), Chart Course (rwK/KüG), Wind (pressure hPa, direction, strength), Sea State (Seegang), Weather (icons/symbols), Current (Strom), Heel (Lage), Sail Configuration (G, F, S, StF) or Motor run hours, Log reading, Distance, and GPS Coordinate with custom remarks. +- **Daily Summaries**: Position morning & evening, freshwater/fuel stock checks (morning stock, refilled, evening stock, daily consumption). +- **Sign-off**: Signatures of Skipper and Crew (names in block letters + signature). + +### 3. Smart Integrations (Assistance) +- **OpenWeatherMap Integration**: Automatically query and pre-fill wind direction/strength, pressure, and weather state based on geographical coordinates. +- **GPS Coordinates Capture**: Fetch current latitude/longitude via device GPS and pre-fill coordinates into log entries. + +### 4. Data Management & Privacy +- **Local Database (IndexedDB)**: Direct database queries and local storage in browser sandbox. +- **CSV Data Export**: Generate and download formatted CSV logbooks directly, or trigger local email/message sharing. +- **Offline Assets & Service Worker**: Cache all HTML, JS, CSS, and assets so the application runs completely disconnected. + +## Feature Scoping: Table Stakes vs Differentiators + +| Feature | Category | Type | Complexity | Notes | +|---------|----------|------|------------|-------| +| Vessel Profile | Stammdaten | Table Stake | Low | Form entry with validation. | +| Crew Registry | Stammdaten | Table Stake | Low | Up to 6 profiles, standard fields. | +| Logbook Form | Logbuch | Table Stake | Medium | Complex form containing wind, course, and sails. | +| Deviation Table | Stammdaten | Table Stake | Low | Grid mapping MgK to Abl. | +| CSV Export | Data | Table Stake | Medium | Client-side CSV generation and download trigger. | +| Local Storage | Data | Table Stake | Medium | IndexedDB schema setup and migration. | +| Offline PWA | System | Table Stake | Medium | Service Worker configuration. | +| GPS Fetching | Assistance | Differentiator | Low | HTML5 Geolocation API integration. | +| OpenWeather API | Assistance | Differentiator | Medium | Needs API key, coordinates, and fallback for offline. | +| Adaptive OS UI | UI/UX | Differentiator | High | Modifying UI based on UserAgent/OS detection. | + +## Anti-Features (Do Not Build) + +- **Cloud DB Sync**: Violates local-only privacy constraint. +- **Central User Login / Registration**: No remote accounts; the app is immediately active upon loading. +- **Remote Sharing Server**: Logbook files must be exported directly from the device (CSV download or local email handler). + +## Dependencies & Risk Analysis + +1. **Weather API Dependency**: OpenWeatherMap API requires internet access. If the user is offline (common at sea), the API will fail. + - *Risk Mitigation*: Implement clean offline fallback. Inform the user they are offline and allow manual weather entry. +2. **GPS Geolocation Dependency**: Requires browser permissions. Device GPS can be slow to lock or unavailable on some tablets without GPS chips. + - *Risk Mitigation*: Allow manual entry of latitude and longitude as fallback. +3. **PWA Storage Cleared by OS**: iOS Safari sometimes purges IndexedDB for apps not added to the home screen if they are unused for 7+ days. + - *Risk Mitigation*: Display a warning prompting the user to install the app to the home screen (PWA installation protects storage) and encourage regular backups using the CSV export. + +--- +*Features research for: Kapteins Daagbox PWA* +*Researched: 2026-05-26* diff --git a/.planning/research/PITFALLS.md b/.planning/research/PITFALLS.md new file mode 100644 index 0000000..806d0aa --- /dev/null +++ b/.planning/research/PITFALLS.md @@ -0,0 +1,52 @@ +# Pitfalls Research + +**Domain:** Offline-first PWA, Local Storage, Geolocation +**Researched:** 2026-05-26 +**Confidence:** HIGH + +## Common Domain Pitfalls + +### 1. iOS Safari IndexedDB Expiration Policy +- **Problem**: Apple iOS Safari has a strict policy where IndexedDB data can be deleted if the user does not open the website for 7 days. This only affects standard websites, but if the app is installed as a PWA on the Home Screen, it is exempt from this rule. +- **Warning Signs**: Logbook entries or vessel profile data disappearing after a week of inactivity. +- **Prevention Strategy**: + - Add an onboarding notification prompting users to install the app on their Home Screen. + - Implement a persistent storage request using the Storage Manager API (`navigator.storage.persist()`) when supported. + - Encourage the user to download CSV backups regularly. + - Show a prominent "Storage Status: Persistent/Temporary" badge in Settings. + +### 2. Network Timeouts and Offline Weather API Calls +- **Problem**: When out at sea, cellular network connections are often weak or non-existent. Attempting to fetch OpenWeatherMap API details can hang the browser, causing the form to freeze or crash if timeouts are not managed. +- **Warning Signs**: The UI stops responding or loading spinner rotates infinitely when user clicks the weather lookup button. +- **Prevention Strategy**: + - Enforce a strict 5-second timeout on all API fetch requests. + - Check network state via `navigator.onLine` before making requests. If offline, instantly skip the request, show a toast notification ("Offline: Weather lookup skipped"), and fall back to manual form fields. + - Wrap all API integrations in robust `try...catch` blocks to prevent unhandled promise rejections. + +### 3. Inaccurate or Slow GPS Geolocations +- **Problem**: Geolocation requests in browsers can fail or return low-accuracy positions, especially when using devices without a dedicated GPS chip (like Wi-Fi-only iPads or laptops) or when indoors/below deck. +- **Warning Signs**: Lat/Long coordinates are empty, coordinates point to the wrong city (based on outdated IP databases), or the browser prompts times out. +- **Prevention Strategy**: + - Set `enableHighAccuracy: true` in the Geolocation options. + - Configure a `timeout: 10000` (10 seconds) so the app does not wait indefinitely. + - Check the `accuracy` parameter returned by the API; if it exceeds 100 meters, warn the user with a subtle yellow icon near the coordinates. + - Always allow the coordinates to be typed or corrected manually. + +### 4. PWA Service Worker Update Lock (Stale Apps) +- **Problem**: A default Service Worker setup caches all files and might serve older app versions indefinitely, even after bug fixes are deployed. If the user loads the app, they keep getting the old cache unless they close all tabs. +- **Warning Signs**: Code changes are deployed, but the user's mobile screen still displays the old version. +- **Prevention Strategy**: + - Use `vite-plugin-pwa`'s "Prompt for Update" behavior instead of auto-updating. + - Detect service worker updates and show a Toast element: "New version available. [Reload to update]". + - Trigger `window.location.reload(true)` upon user agreement. + +### 5. Logbook Form Auto-Save (Drafts) +- **Problem**: Skipper is in the middle of filling out a logbook entry during rough seas, gets distracted, and the browser tab closes or reloads. All typed text (which they might have measured manually) is lost. +- **Warning Signs**: User frustration from losing details of an event due to a browser crash or navigation error. +- **Prevention Strategy**: + - Implement an auto-save mechanism that writes the active form draft to IndexedDB (or LocalStorage) every 10 seconds. + - On launching the logbook entry form, check if a draft exists and offer to restore it. + +--- +*Pitfalls research for: Kapteins Daagbox PWA* +*Researched: 2026-05-26* diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md new file mode 100644 index 0000000..0c1b6d0 --- /dev/null +++ b/.planning/research/STACK.md @@ -0,0 +1,88 @@ +# Stack Research + +**Domain:** Mobile-first, Offline-first PWA +**Researched:** 2026-05-26 +**Confidence:** HIGH + +## Recommended Stack + +We recommend a **React + TypeScript + Vite** stack wrapped with **vite-plugin-pwa** (Workbox) and **Dexie.js** (IndexedDB) for local data storage. This web stack compiles to extremely lightweight assets that load fast on poor connections, works 100% offline, and can easily be packaged using Capacitor if native iOS/Android store apps are required later. + +### Core Technologies + +| Technology | Version | Purpose | Why Recommended | +|------------|---------|---------|-----------------| +| **React** | 18.x / 19.x | UI Library | Component-driven architecture allows building a modular, reactive UI that easily handles state transitions for logbook forms. | +| **TypeScript** | 5.x | Language | Enforces strict type safety across logbook entries and crew models, preventing runtime errors. | +| **Vite** | 5.x | Build Tool | Extremely fast bundler and dev server; offers direct support for PWAs via plugins. | +| **TailwindCSS** / **Vanilla CSS** | 3.x / 4.x | Styling | Allows responsive, adaptive styling to match Android/iOS aesthetics and handles mobile viewport constraints. | + +### Supporting Libraries + +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| **Dexie.js** | 4.x | IndexedDB Wrapper | Required for robust, structured offline-first storage of ship data and log entries. | +| **vite-plugin-pwa** | 0.20.x | PWA / Service Worker | Handles automatic service worker registration, offline caching of assets, and install prompts. | +| **react-i18next** | 14.x | Multilingual (l18n) | Seamless translation management for German and English with automatic language detection. | +| **lucide-react** | 0.300.x | SVG Icons | Light, modern icon library for weather states, navigation, and logbook actions. | + +### Development Tools + +| Tool | Purpose | Notes | +|------|---------|-------| +| **ESLint / Prettier** | Code linting and formatting | Standardizes code style and catches early bugs. | +| **Lighthouse / DevTools** | PWA and Performance auditing | Essential for testing offline loading and installability criteria. | + +## Installation + +```bash +# Core & UI +npm install react react-dom lucide-react + +# Storage, PWA & Localization +npm install dexie dexie-react-hooks react-i18next i18next i18next-browser-languagedetector + +# Dev Dependencies +npm install -D typescript @types/react @types/react-dom vite @vitejs/plugin-react vite-plugin-pwa +``` + +## Alternatives Considered + +| Recommended | Alternative | When to Use Alternative | +|-------------|-------------|-------------------------| +| **Vite React PWA** | **Flutter Web PWA** | Flutter is strong for native compilation, but Flutter Web suffers from large canvas-kit bundles (2.5MB+ JS load size), which makes it poor for remote maritime connections. Use Flutter if native store presence is the absolute priority from Day 1 and web-performance is secondary. | +| **Dexie.js (IndexedDB)** | **LocalStorage** | LocalStorage is simpler but limited to ~5MB and is synchronous. IndexedDB handles large datasets (e.g. photos in logbooks, years of log entries) asynchronously and is recommended for production. | + +## What NOT to Use + +| Avoid | Why | Use Instead | +|-------|-----|-------------| +| **Firebase / Supabase** | Requires online connection for core operations; violates "local-only" strict privacy constraint. | Dexie.js + Local IndexedDB | +| **Bootstrap** | Heavy, outdated styling that doesn't adapt well to modern native mobile looks. | TailwindCSS / CSS variables | + +## Stack Patterns by Variant + +**If strict local privacy is required:** +- Use IndexedDB (via Dexie.js) for storage. +- Because IndexedDB runs entirely in the user's browser sandbox and has no cloud sync, guaranteeing absolute data ownership. + +**If poor connectivity is expected:** +- Configure Workbox Service Worker in "CacheFirst" or "StaleWhileRevalidate" mode. +- Because it ensures the application shell loads immediately even with 0% network connection. + +## Version Compatibility + +| Package A | Compatible With | Notes | +|-----------|-----------------|-------| +| `vite-plugin-pwa@0.20.x` | `vite@5.x` | Standard integration for Vite-based PWAs. | +| `dexie-react-hooks@4.x` | `react@18.x` | Allows React components to reactively observe IndexedDB query changes. | + +## Sources + +- [Vite PWA Docs](https://vite-pwa-org.netlify.app/) — PWA caching and service worker strategies. +- [Dexie.js Documentation](https://dexie.org/) — Schema migrations and IndexedDB reactive binding. +- [Web Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) — Browser geolocation capabilities. + +--- +*Stack research for: Kapteins Daagbox PWA* +*Researched: 2026-05-26* diff --git a/.planning/research/SUMMARY.md b/.planning/research/SUMMARY.md new file mode 100644 index 0000000..ac0cbcd --- /dev/null +++ b/.planning/research/SUMMARY.md @@ -0,0 +1,123 @@ +# Project Research Summary + +**Project:** Kapteins Daagbox (Kapteins Daagbog) +**Domain:** Offline-first PWA, Maritime Logbook +**Researched:** 2026-05-26 +**Confidence:** HIGH + +## Executive Summary + +Kapteins Daagbox is an offline-first PWA that serves as a digital ship's logbook for private yachts. It places a primary emphasis on complete data privacy by storing all yacht, crew, and journal entries entirely local to the user's browser database (IndexedDB). + +The recommended approach uses **Vite + React + TypeScript + Dexie.js + TailwindCSS**, which guarantees a lightweight bundle that loads quickly on low-bandwidth mobile connections at sea. The app incorporates browser Geolocation APIs for automatic GPS coordinate capture and integrates with OpenWeatherMap for sea/weather pre-filling. + +Key risks include data loss due to OS storage reclamation policies (particularly on iOS Safari) and API timeouts when connections fail. These are mitigated by instructing the user to install the app as a PWA on their Home Screen, enabling persistent storage APIs, and using local draft autosaving along with regular CSV backups. + +## Key Findings + +### Recommended Stack + +We recommend React with Vite and TypeScript for fast rendering and development. [STACK.md](STACK.md) details the tools and configurations. + +**Core technologies:** +- **React + TS + Vite**: Builds a fast, responsive mobile app compiled to lightweight static assets. +- **Dexie.js (IndexedDB)**: An asynchronous, robust client-side database with reactive binding for UI state management. +- **vite-plugin-pwa (Workbox)**: Configures offline asset caching, service worker hooks, and updates. +- **react-i18next**: Handles German/English localizations and browser language auto-detection. + +### Expected Features + +Detailed scoping is tracked in [FEATURES.md](FEATURES.md). + +**Must have (table stakes):** +- **Vessel Profile & Crew Registry**: Stammdaten forms capturing yacht specifications and up to 6 crew records. +- **Steuertafel (Deviation table)**: Grid aligning compass headings with magnetic deviation. +- **Logbook Forms**: Rich fields capturing journey details, course, wind, sails, sea state, and daily fuel/water checks. +- **Local Database & Offline Capability**: Persistent client-side storage and offline asset availability. +- **CSV Data Export**: Generating and downloading logs in standard CSV format. + +**Should have (differentiators):** +- **GPS Pre-filling**: Instant fetch of coordinates via browser Geolocation. +- **Weather API Integration**: Prefill coordinates' weather and wind parameters via OpenWeatherMap. +- **Adaptive OS UI**: CSS themes styled to blend with Android Material or iOS Cupertino designs. + +### Architecture Approach + +Detailed in [ARCHITECTURE.md](ARCHITECTURE.md). + +**Major components:** +1. **IndexedDB (Dexie)**: Structured database tables for yacht metadata, crew, compass deviations, and logbook entries. +2. **App Shell UI**: A single-page layout with responsive page navigation, form views, and a storage status check. +3. **Application Services**: Isolated logic handlers for GPS acquisition, OpenWeather API requests, translation bundles, and CSV builders. +4. **Service Worker Cache**: Local static asset container ensuring immediate PWA load times. + +### Critical Pitfalls + +Mitigation steps are outlined in [PITFALLS.md](PITFALLS.md). + +1. **iOS Safari Storage Purge**: Safely bypassed by adding instructions for PWA installation (preventing Safari's 7-day inactivity purge) and requesting persistent storage. +2. **Offline Weather API Timeouts**: Resolved by checking connection status and setting a strict 5-second timeout on requests. +3. **GPS Fetch Delays**: Mitigated by setting high-accuracy timeouts, validating precision, and offering full manual entry. +4. **SW Caching Stale Updates**: Handled by adding update prompts instead of automatic service worker overrides. + +## Implications for Roadmap + +Based on research and dependencies, we suggest a 4-phase rollout: + +### Phase 1: Foundation & Data Infrastructure +- **Rationale**: Setting up the development bundle, service worker, and local database first ensures all subsequent screens can read/write data in real-time. +- **Delivers**: PWA shell, Dexie DB database models, and English/German language configuration. +- **Addresses**: DATA-01 (Local storage), DATA-02 (Offline), GEN-02 (Multilingual). +- **Avoids**: Service worker stale caching updates (set up correctly at the beginning). + +### Phase 2: Vessel & Crew Management (Stammdaten) +- **Rationale**: Master data must be created before a skipper can log a journey. +- **Delivers**: Vessel specifications form, Crew lists management, and the Compass Deviation Grid. +- **Addresses**: MASTER-01 (Vessel/Crew data), Steuertafel. +- **Uses**: Dexie tables for yacht, crew, and deviation. + +### Phase 3: Logbook Entries & Integration +- **Rationale**: Core logbook entries require the vessel profile and deviation calculations defined in Phase 2. +- **Delivers**: Log list, log entry form with weather/sea/sail selectors, GPS position pre-fill, and OpenWeather API hook. +- **Addresses**: LOG-01 (Forms), LOG-02 (Weather), LOG-03 (GPS). +- **Avoids**: GPS fetch delays and offline API hangs (using timeouts and fallbacks). + +### Phase 4: Data Export & UI Polish +- **Rationale**: Finalizing data portability and polishing visual alignment. +- **Delivers**: CSV export, local mail/share handlers, storage persistence checks, and iOS/Android adaptive themes. +- **Addresses**: DATA-03 (CSV Export), GEN-01 (Mobile-first adaptive UI). +- **Avoids**: iOS storage purges (by implementing persistent storage requests and PWA install warnings). + +### Phase Ordering Rationale + +The suggested order establishes database schemas first, followed by static profiles, dynamic transaction forms, and finally export utilities. This minimizes developer friction by ensuring database queries can be fully tested in mock views before building the complex logbook interface. + +### Research Flags + +- **Phase 3 (Logbook & API integration)**: Needs careful handling of API key configuration (stored client-side in LocalStorage, not bundled in public repo for security) and geolocation permissions. +- **Phase 4 (PWA Storage & UI adaptation)**: Requires verification of persistent storage requests across iOS/Android browsers. + +## Confidence Assessment + +| Area | Confidence | Notes | +|------|------------|-------| +| Stack | HIGH | Vite React TS is standard for offline PWAs. Dexie is well-maintained and reliable. | +| Features | HIGH | Extracted directly from official PDF example logbook layout. | +| Architecture | HIGH | Standard client-side-only architecture without server dependencies. | +| Pitfalls | HIGH | Service worker caching and iOS storage limits are thoroughly documented in developer circles. | + +**Overall confidence:** HIGH + +### Gaps to Address + +- **OpenWeatherMap API Key**: The app requires an API key. We will implement a setting allowing users to provide their own OpenWeatherMap API key (saved in LocalStorage) so that the app remains open-source, client-side, and avoids developer key exposure. + +## Sources + +- [Vite PWA Docs](https://vite-pwa-org.netlify.app/) +- [Dexie.js Documentation](https://dexie.org/) +- [Apple WebKit Storage Guidelines](https://webkit.org/blog/10218/full-third-party-cookie-blocking-and-more/) + +--- +*Research completed: 2026-05-26* +*Ready for roadmap: yes*