elpatron/kapteins-daagbok
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity

docs: create roadmap (4 phases)

Browse Source
This commit is contained in:
elpatron
2026-05-26 22:57:13 +02:00
parent 8de7052082
commit 1f056ef127
4 changed files with 275 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+22 -24
View File
@@ -60,35 +60,33 @@ These requirements are deferred to future milestones.
## Traceability ## Traceability
*Will be populated during roadmap creation.*
| Requirement | Phase | Status | | Requirement | Phase | Status |
|-------------|-------|--------| |-------------|-------|--------|
| UI-01 | Pending | Pending | | UI-01 | Phase 4 | Pending |
| UI-02 | Pending | Pending | | UI-02 | Phase 1 | Pending |
| UI-03 | Pending | Pending | | UI-03 | Phase 1 | Pending |
| VESSEL-01 | Pending | Pending | | VESSEL-01 | Phase 2 | Pending |
| VESSEL-02 | Pending | Pending | | VESSEL-02 | Phase 2 | Pending |
| VESSEL-03 | Pending | Pending | | VESSEL-03 | Phase 2 | Pending |
| DEV-01 | Pending | Pending | | DEV-01 | Phase 2 | Pending |
| DEV-02 | Pending | Pending | | DEV-02 | Phase 2 | Pending |
| LOG-01 | Pending | Pending | | LOG-01 | Phase 3 | Pending |
| LOG-02 | Pending | Pending | | LOG-02 | Phase 3 | Pending |
| LOG-03 | Pending | Pending | | LOG-03 | Phase 3 | Pending |
| LOG-04 | Pending | Pending | | LOG-04 | Phase 3 | Pending |
| LOG-05 | Pending | Pending | | LOG-05 | Phase 3 | Pending |
| INT-01 | Pending | Pending | | INT-01 | Phase 3 | Pending |
| INT-02 | Pending | Pending | | INT-02 | Phase 3 | Pending |
| INT-03 | Pending | Pending | | INT-03 | Phase 3 | Pending |
| SYS-01 | Pending | Pending | | SYS-01 | Phase 1 | Pending |
| SYS-02 | Pending | Pending | | SYS-02 | Phase 1 | Pending |
| SYS-03 | Pending | Pending | | SYS-03 | Phase 4 | Pending |
| SYS-04 | Pending | Pending | | SYS-04 | Phase 4 | Pending |
**Coverage:** **Coverage:**
- v1 requirements: 20 total - v1 requirements: 20 total
- Mapped to phases: 0 - Mapped to phases: 20
- Unmapped: 20 ⚠️ - Unmapped: 0 ✓
--- ---
*Requirements defined: 2026-05-26* *Requirements defined: 2026-05-26*
.planning/ROADMAP.md
+87
View File
@@ -0,0 +1,87 @@
# Roadmap: Kapteins Daagbox
## Overview
Kapteins Daagbox will be built in four logical phases following a clean data-to-UI progression. We start by building the PWA and local database foundations (Phase 1), followed by the vessel and crew static profile editors (Phase 2), then the core logbook journal entries and dynamic sensors/API integrations (Phase 3), and finally, local CSV export utilities and host platform CSS adjustments (Phase 4).
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3, 4): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
- [ ] **Phase 1: Foundation & Data Infrastructure** - Initialize PWA, database, and translations
- [ ] **Phase 2: Master Data Management (Stammdaten)** - Build boat profile, crew manager, and deviation table
- [ ] **Phase 3: Logbook Entries & Integration** - Form sheets, GPS coordinates, and Weather API integrations
- [ ] **Phase 4: CSV Export & UI Polish** - CSV generation, share triggers, and adaptive CSS layout
## Phase Details
### Phase 1: Foundation & Data Infrastructure
**Goal**: Initialize the PWA development bundle, service worker caching, IndexedDB database client, and translation hooks.
**Depends on**: Nothing (first phase)
**Requirements**: UI-02, UI-03, SYS-01, SYS-02
**Success Criteria**:
1. App loads instantly with offline assets from a service worker.
2. German and English languages are switchable via menu, and the initial language is auto-detected from browser locales.
3. Dexie.js database client is initialized with working Yacht, Crew, Deviation, and LogEntry tables.
**Plans**: 2 plans
Plans:
- [ ] 01-01: Initialize Vite React TS, configure vite-plugin-pwa, set up the layout shell, and add react-i18next translations.
- [ ] 02-01: Initialize Dexie.js schemas and implement a Database Settings view to check storage capability.
### Phase 2: Master Data Management (Stammdaten)
**Goal**: Implement forms for vessel profile metadata, skipper and crew personal files, and the compass deviation grid.
**Depends on**: Phase 1
**Requirements**: VESSEL-01, VESSEL-02, VESSEL-03, DEV-01, DEV-02
**Success Criteria**:
1. User can successfully save and update the Yacht profile.
2. User can add, edit, and remove up to 6 crew records.
3. User can input compass headings (MgK) and save corresponding magnetic deviation values.
**Plans**: 2 plans
Plans:
- [ ] 02-01: Build Yacht and Crew editing components and wire them to Dexie.js collections.
- [ ] 02-02: Build the Deviation grid (Steuertafel) covering 000° to 360° headings.
### Phase 3: Logbook Entries & Integration
**Goal**: Develop the journey listing, entry form sheets, GPS coordinate prefill, and OpenWeatherMap assistance lookup.
**Depends on**: Phase 2
**Requirements**: LOG-01, LOG-02, LOG-03, LOG-04, LOG-05, INT-01, INT-02, INT-03
**Success Criteria**:
1. User can create daily logbook entries, record hourly events, and track water/diesel consumption.
2. User can pre-fill current coordinates with one tap (via browser Geolocation).
3. User can fetch and prefill weather description, pressure, and wind speed/direction using OpenWeatherMap API (with offline fallbacks).
4. User can sign off the daily entry.
**Plans**: 2 plans
Plans:
- [ ] 03-01: Build logbook list view and daily log entry header, sails, and consumption forms.
- [ ] 03-02: Implement event log forms, Geolocation API integration, and OpenWeatherMap service helper.
### Phase 4: CSV Export & UI Polish
**Goal**: Implement client-side CSV file download, share dialog hooks, local storage persistent request, and platform CSS themes.
**Depends on**: Phase 3
**Requirements**: SYS-03, SYS-04, UI-01
**Success Criteria**:
1. User can download a standard CSV file matching their logbook entries.
2. User can launch the native mail or share panel with the generated CSV data.
3. The interface renders elements in platform-adaptive styles matching iOS Cupertino or Android Material.
**Plans**: 2 plans
Plans:
- [ ] 04-01: Implement CSV export service and link it to the Web Share API.
- [ ] 04-02: Implement storage persistence prompt, PWA install prompt warnings, and apply OS-adaptive UI themes.
## Progress
**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation & Data Infrastructure | 0/2 | Not started | - |
| 2. Master Data Management (Stammdaten) | 0/2 | Not started | - |
| 3. Logbook Entries & Integration | 0/2 | Not started | - |
| 4. CSV Export & UI Polish | 0/2 | Not started | - |
.planning/STATE.md
+63
View File
@@ -0,0 +1,63 @@
# Project State
## Project Reference
See: .planning/PROJECT.md (updated 2026-05-26)
**Core value:** A private, offline-first mobile ship's logbook that stores all data locally, offering GPS/weather assistance and easy CSV sharing.
**Current focus:** Phase 1: Foundation & Data Infrastructure
## Current Position
Phase: 1 of 4 (Foundation & Data Infrastructure)
Plan: 1 of 2 in current phase
Status: Ready to plan
Last activity: 2026-05-26 — Project initialized
Progress: [░░░░░░░░░░] 0%
## Performance Metrics
**Velocity:**
- Total plans completed: 0
- Average duration: 0 min
- Total execution time: 0.0 hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 1. Foundation & Data Infrastructure | 0/2 | - | - |
| 2. Master Data Management | 0/2 | - | - |
| 3. Logbook Entries & Integration | 0/2 | - | - |
| 4. CSV Export & UI Polish | 0/2 | - | - |
**Recent Trend:**
- Last 5 plans: []
- Trend: Stable
*Updated after each plan completion*
## Accumulated Context
### Decisions
Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:
- [Init]: Local-Only Storage — IndexedDB selected to satisfy absolute privacy constraints.
- [Init]: PWA Architecture — React PWA selected for fast, lightweight loading and cross-platform installation.
### Pending Todos
None yet.
### Blockers/Concerns
None yet.
## Session Continuity
Last session: 2026-05-26 22:55
Stopped at: Project initialized
Resume file: None
GEMINI.md
+103
View File
@@ -0,0 +1,103 @@
<!-- GSD:project-start source:PROJECT.md -->
## Project
**Kapteins Daagbox (Kapteins Daagbog)**
Kapteins Daagbox is a modern, mobile-first Progressive Web Application (PWA) designed for private yacht owners and captains to manage their ship's logbook digitally. The application enables users to log vessel master data, owner details, crew information, and daily logbook entries conforming to official maritime standards.
**Core Value:** Providing a private-by-design, fully offline-capable mobile maritime logbook that respects absolute user privacy by storing data 100% locally on the device while assisting the skipper with GPS position capture and automated weather integration.
### Constraints
- **Storage**: Must be stored exclusively client-side (IndexedDB / LocalStorage / Origin Private File System).
- **Privacy**: No external telemetry or cloud database connections.
- **Offline**: The app must load and operate fully without internet access (using Service Workers).
- **Languages**: German and English.
<!-- GSD:project-end -->
<!-- GSD:stack-start source:research/STACK.md -->
## Technology Stack
## Recommended Stack
### 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
# Core & UI
# Storage, PWA & Localization
# Dev Dependencies
## 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
- 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.
- 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.
<!-- GSD:stack-end -->
<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions
Conventions not yet established. Will populate as patterns emerge during development.
<!-- GSD:conventions-end -->
<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture
Architecture not yet mapped. Follow existing patterns found in the codebase.
<!-- GSD:architecture-end -->
<!-- GSD:workflow-start source:GSD defaults -->
## GSD Workflow Enforcement
Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.
Use these entry points:
- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks
- `/gsd-debug` for investigation and bug fixing
- `/gsd-execute-phase` for planned phase work
Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
<!-- GSD:workflow-end -->
<!-- GSD:profile-start -->
## Developer Profile
> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.
> This section is managed by `generate-claude-profile` -- do not edit manually.
<!-- GSD:profile-end -->