elpatron/kapteins-daagbok
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity
Files
master
kapteins-daagbok/.planning/research/SUMMARY.md
T

6.9 KiB
Executable File
Raw Permalink Blame History

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 synced with a zero-knowledge backend server, serving as a secure digital ship's logbook for private yachts. It guarantees data privacy via client-side End-to-End Encryption (E2E), ensuring the server only stores encrypted payloads.

The recommended stack features a React + TS + Vite frontend, a Node.js Express + Prisma + PostgreSQL backend, Dexie.js for local caching, and WebAuthn for passwordless Passkey login. E2E key derivation uses biometric/hardware PRF input or a 12-word recovery phrase.

Key risks include loss of client-side encryption keys (causing unrecoverable server data), browser compatibility with WebAuthn, and concurrent offline synchronization conflicts. These are mitigated by a mandatory recovery phrase verification on registration, using standard security key fallbacks, and applying Last-Write-Wins timestamps to sync packets.

Key Findings

Recommended Stack

We recommend a React with Vite client paired with a Node.js + Express backend using Prisma and PostgreSQL. STACK.md details the configurations.

Core technologies:

  • React + TS + Vite / Node.js Express: Full-stack TypeScript environment.
  • PostgreSQL & Prisma: Backend storage for user credentials and encrypted payloads.
  • Dexie.js (IndexedDB): Client-side local transaction cache.
  • WebAuthn (@simplewebauthn): Passkey integration for passwordless logins.
  • Web Crypto API: High-performance, browser-native client encryption.

Expected Features

Detailed scoping is tracked in FEATURES.md.

Must have (table stakes):

  • Passkey Auth & E2E Encryption: Biometric user onboarding and client-side AES-GCM data encryption.
  • Multi-Logbook Manager: Dashboard UI to manage and switch between multiple ship logbooks.
  • Stammdaten Forms: Yacht profile, skipper/crew profiles, and Deviation grids.
  • Sync Protocol: Local-first caching synced securely to PostgreSQL payloads.
  • CSV Data Export: Decrypted on-the-fly client-side CSV downloads.

Should have (differentiators):

  • GPS & Weather Integration: Browser Geolocation API and OpenWeatherMap lookup with offline fallbacks.
  • Adaptive OS UI: Platforms adaptive Cupertino (iOS) and Material (Android) themes.

Architecture Approach

Detailed in ARCHITECTURE.md.

Major components:

  • Zero-Knowledge Backend: Handles Passkey verification and stores E2E encrypted string blocks without access to user keys.
  • IndexedDB Caching Layer: Local cache database holding encrypted versions of active logbooks and syncQueue.
  • E2E Cryptographic Service: Web Crypto utilities implementing PRF-derived keys and BIP39 fallback phrases.
  • Offline PWA Shell: Service worker caching front-end assets for offline launch.

Critical Pitfalls

Mitigation steps are outlined in PITFALLS.md.

  1. E2E Key Recovery Loss: Force recovery phrase validation during sign-up to prevent permanent data loss.
  2. WebAuthn Compatibility: Check authenticator status and fallback to hardware security keys.
  3. Offline Sync Conflicts: Utilize transaction logs, last-write-wins rules, and append-only entries with merge warnings.
  4. Offline Weather/GPS Timeouts: Set 5-second weather fetch timeouts and 10-second GPS lock limits.

Implications for Roadmap

Based on research and dependencies, we suggest a revised 4-phase rollout:

Phase 1: Foundation, Auth & E2E Crypto

  • Rationale: Creating the client PWA and Express backend repositories first allows building the core security boundary (Passkeys and Web Crypto key derivation) before handling user data.
  • Delivers: Node backend, Prisma schema, WebAuthn options endpoints, and Web Crypto PRF/recovery helpers.
  • Addresses: AUTH-01 (Passkeys), CRYPTO-01/02/03 (E2E encryption), UI-02/03 (Languages).

Phase 2: Sync Protocol & Multi-Logbooks

  • Rationale: Developing the caching database, sync protocol, and multi-logbook views next ensures all subsequent UI features sync automatically in the background.
  • Delivers: Multi-logbook dashboards, Local IndexedDB cache tables, and synchronization transaction queue API.
  • Addresses: AUTH-02/03 (Multi-logbooks), SYS-02 (Local-first sync).

Phase 3: Master Data & Log entries

  • Rationale: The UI forms can now read/write securely from the E2E-encrypted sync layer built in Phase 2.
  • Delivers: Yacht forms, Crew lists, deviation grids, and journal entry records synced to the database.
  • Addresses: VESSEL-01/02/03 (Boat/crew profiles), DEV-01/02 (Deviation grid), LOG-01/02/03/04/05 (Journal logs), INT-01/02/03 (GPS & Weather).

Phase 4: CSV Export & UI Polish

  • Rationale: Compiling exports and polishing OS-native layouts completes the user cycle.
  • Delivers: Client-side decryption CSV builder, sync progress indicators, and Material/Cupertino styles.
  • Addresses: SYS-03/04 (CSV Share/Export), UI-01 (Adaptive UI layout).

Phase Ordering Rationale

The suggested order establishes the backend server and cryptographic vault first. Next, it handles multi-logbook syncing so that when the master forms and log entries are coded in Phase 3, they plug immediately into a working, encrypted offline sync pipeline.

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 Express, Prisma, Postgres, and Dexie are highly reliable. SimpleWebAuthn makes Passkey integration straightforward.
Features HIGH Expanded requirements map directly to nautical guidelines while preserving user ownership.
Architecture HIGH Hybrid client-side E2E zero-knowledge design has been proven by services like Proton.
Pitfalls HIGH Identified key recovery and offline sync conflict risks early with mitigation strategies.

Overall confidence: HIGH

Gaps to Address

  • OpenWeatherMap API Key: Stored client-side in LocalStorage to avoid server exposure or leakage of developer keys.
  • Database Hosting: Will require configuring a PostgreSQL instance (e.g. Docker container locally or cloud host for production).

Sources

Research completed: 2026-05-26 Ready for roadmap: yes

Reference in New Issue View Git Blame Copy Permalink