122 lines
6.9 KiB
Markdown
Executable File
122 lines
6.9 KiB
Markdown
Executable File
# 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](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](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](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](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
|
|
|
|
- [Vite PWA Docs](https://vite-pwa-org.netlify.app/)
|
|
- [Dexie.js Documentation](https://dexie.org/)
|
|
- [WebAuthn Specification & SimpleWebAuthn Docs](https://webauthn.guide/)
|
|
- [Web Crypto API Reference (W3C)](https://www.w3.org/TR/WebCryptoAPI/)
|
|
|
|
---
|
|
*Research completed: 2026-05-26*
|
|
*Ready for roadmap: yes*
|