nitrix
6aeb4b8bca
- Move cross-cutting docs (personas, design system, implementation phases, Ideen.md) to .specify/memory/ - Move cross-cutting research and plans to .specify/memory/research/ and .specify/memory/plans/ - Extract 5 setup tasks from spec/setup-tasks.md into individual specs/001-005/spec.md files with spec-kit template format - Extract 20 user stories from spec/userstories.md into individual specs/006-026/spec.md files with spec-kit template format - Relocate feature-specific research and plan docs into specs/[feature]/ - Add spec-kit constitution, templates, scripts, and slash commands - Slim down CLAUDE.md to Claude-Code-specific config, delegate principles to .specify/memory/constitution.md - Update ralph.sh with stream-json output and per-iteration logging - Delete old spec/ and docs/agents/ directories - Gitignore Ralph iteration JSONL logs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
74 lines
4.7 KiB
Markdown
74 lines
4.7 KiB
Markdown
# Feature Specification: Install as Progressive Web App
|
|
|
|
**Feature**: `020-pwa`
|
|
**Created**: 2026-03-06
|
|
**Status**: Draft
|
|
**Source**: Migrated from spec/userstories.md
|
|
|
|
## User Scenarios & Testing
|
|
|
|
### User Story 1 - Install the app on a mobile or desktop device (Priority: P1)
|
|
|
|
**As a** guest,
|
|
**I want to** install the app on my device from the browser,
|
|
**so that** it feels like a native app and I can launch it directly from my home screen.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the app is open in a supported mobile browser, **When** the user opens the browser menu, **Then** an "Add to Home Screen" or install prompt is available because the app serves a valid manifest and a registered service worker.
|
|
|
|
2. **Given** the user has installed the app, **When** they launch it from the home screen, **Then** the app opens in standalone mode — without browser address bar or navigation chrome.
|
|
|
|
3. **Given** the app is installed, **When** the user views their device's home screen or app switcher, **Then** the configured icon and app name are displayed.
|
|
|
|
4. **Given** the user has visited the app previously, **When** they open the app again (including on a slow or offline connection), **Then** previously loaded pages and assets load quickly due to service worker caching.
|
|
|
|
5. **Given** the app is installed and launched from the home screen, **When** the app starts, **Then** the start URL is the root page (`/`), which serves the local event overview (US-7), so returning users see their tracked events immediately.
|
|
|
|
### User Story 2 - Serve a valid web app manifest (Priority: P1)
|
|
|
|
**As a** browser,
|
|
**I want** the app to serve a well-formed web app manifest,
|
|
**so that** I can offer the user an install prompt and render the installed app correctly.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a browser fetches the app's manifest, **Then** it includes at minimum: app name, icons in multiple sizes, standalone display mode, theme color, and a start URL.
|
|
|
|
2. **Given** the manifest and service worker are present, **Then** the app meets browser installability requirements (manifest + registered service worker) so that the install prompt is available on supported browsers.
|
|
|
|
3. **Given** the manifest or service worker loads assets, **Then** no external resources are fetched — all assets referenced are self-hosted.
|
|
|
|
### Edge Cases
|
|
|
|
- Browsers that do not support service workers or PWA installation should still render the app normally — PWA features are an enhancement, not a requirement.
|
|
- If the service worker fails to install (e.g. due to a browser policy), the app must still function as a standard web page.
|
|
- Service worker caching strategy (cache-first, network-first, stale-while-revalidate) is an implementation decision to be determined during implementation.
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-01**: The app serves a valid web app manifest (JSON) accessible at a standard path (e.g. `/manifest.webmanifest` or `/manifest.json`).
|
|
- **FR-02**: The manifest includes at minimum: app name, short name, icons in multiple sizes (e.g. 192x192 and 512x512), `display: "standalone"`, `theme_color`, `background_color`, and `start_url: "/"`.
|
|
- **FR-03**: The app registers a service worker that meets browser installability requirements alongside the manifest.
|
|
- **FR-04**: When launched from the home screen, the app opens in standalone mode without browser navigation chrome.
|
|
- **FR-05**: The app icon and name are shown on the device home screen and in the OS app switcher after installation.
|
|
- **FR-06**: The service worker caches app assets so that repeat visits load quickly.
|
|
- **FR-07**: The manifest's start URL is `/`, serving the local event overview (US-7).
|
|
- **FR-08**: No external resources (CDNs, external fonts, remote icons) are fetched by the manifest or service worker — all assets are self-hosted.
|
|
- **FR-09**: PWA installability does not depend on any backend state — it is a purely frontend concern served by the static assets.
|
|
|
|
### Key Entities
|
|
|
|
- **Web App Manifest**: A static JSON file describing the app's identity, icons, display mode, and start URL. No database storage required.
|
|
- **Service Worker**: A client-side script registered by the app to handle caching and (optionally) offline behavior. No server-side representation.
|
|
|
|
## Success Criteria
|
|
|
|
1. A supported mobile browser shows an "Add to Home Screen" prompt or install banner for the app.
|
|
2. After installation, the app launches in standalone mode with the correct icon and name.
|
|
3. The installed app's start URL leads directly to the local event overview (`/`).
|
|
4. Repeat visits are noticeably faster due to service worker asset caching.
|
|
5. No external resources are loaded by the manifest or service worker — all assets are served from the app's own origin.
|