Files

nitrix 6aeb4b8bca Migrate project artifacts to spec-kit format

- 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>

2026-03-06 20:19:41 +01:00

4.7 KiB

Raw Blame History

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:

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.
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.
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.
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.
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:

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.
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.
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

A supported mobile browser shows an "Add to Home Screen" prompt or install banner for the app.
After installation, the app launches in standalone mode with the correct icon and name.
The installed app's start URL leads directly to the local event overview (/).
Repeat visits are noticeably faster due to service worker asset caching.
No external resources are loaded by the manifest or service worker — all assets are served from the app's own origin.

4.7 KiB Raw Blame History