mobile-flashcard-pwa

Mobile Flashcard PWA

Use this when building a mobile-first study app where the card is the product.

Recommended stack

• Frontend: React + Vite + TypeScript
• Gestures: react-swipeable
• Server: single-port Express serving dist/
• Deployment: PM2 + nginx
• PWA: manifest + service worker + no-cache headers for sw.js and manifest.json

UX rules that worked well

1. Make the card dominate the viewport.
2. Keep non-card chrome tiny — use a discreet top bar only.
3. Remove redundant bottom controls if swipe + tap already cover navigation.
4. On first use, show a small toast: "Swipe sideways to change cards. Tap the card to flip."
5. Persist a seenGestureHint flag in localStorage so the toast is not permanent.
6. If card metadata includes component symbols (like trigrams), show mini visual glyphs next to their names — text alone feels too abstract.
7. For alphabet/symbol-learning apps, do not ship a small conceptual demo with only representative signs if the user wants to “learn the letters/symbols.” Build complete deck coverage first: explicit counts per script, all glyphs visible in a grid, large study cards, search, progress states, and quiz mode. Include a coverage card so gaps are obvious.

Good top bar pattern

• App name
• Progress count (current/total)
• 2-4 compact chips for sequence/view mode
• Avoid settings drawers unless absolutely necessary

Gesture pattern

• Tap card -> flip front/back
• Swipe left/right -> next/previous card
• Reset to front face when changing cards
• For random mode, provide a small Reshuffle pill instead of a full control tray

Sequence mode pattern

Support multiple orderings with a single createStudyDeck() function.

Recommended modes: - canonical / King Wen - user-provided custom sequence (e.g. Human Design) - binary / structural - random

For a custom sequence supplied as an explicit 64-number array: 1. Store the array as a constant. 2. Build const CUSTOM_INDEX: Map<number, number> = new Map(order.map((n, i) => [n, i] as const)) 3. Sort with the map lookup instead of hardcoding many ifs. 4. Add a test that verifies: - first several values match exactly - last value matches exactly - all 64 entries are unique

This avoids mistakes when users hand you a specific sacred/study order they care about.

PWA update pattern that avoids reinstall

This was the important deploy requirement.

In the client

• Register sw.js
• Immediately call registration.update() on load
• Poll registration.update() every ~60s
• Listen for controllerchange and reload once when a new SW takes control, but only if the page already had a controller before registration. Capture const hadController = Boolean(navigator.serviceWorker.controller) before register(), then in controllerchange do nothing on the first install. This avoids iOS standalone PWA first-launch reload loops/white screens.
• Optionally show an Update ready pill/button when updatefound fires

In public/sw.js

• Use a versioned cache name
• Call self.skipWaiting() in install
• Call self.clients.claim() in activate
• Delete old caches in activate
• Use network-first for app shell/assets, falling back to cache
• Do not cache /api/ responses as static app shell

In Express

Serve these with no-cache headers BEFORE express.static(distDir): - /sw.js - /manifest.json

Example headers: - Cache-Control: no-cache, no-store, must-revalidate - Service-Worker-Allowed: / for sw.js

Backend-only token pattern

When the user wants an LLM/API token in the app but not exposed to the browser: 1. Load env on the server with import 'dotenv/config' 2. Keep the token in .env only 3. Never surface the raw key to the frontend 4. If useful, expose only a boolean status endpoint like /api/config-status -> { hasOpenRouter: true }

Reusing an existing OpenRouter key

If another app on the same VPS already uses OpenRouter: - Check that app’s .env or PM2 ecosystem config - Copy the key into the new app’s .env - Keep .env gitignored - Add .env.example with placeholder values only

LLM enrichment script pattern

For datasets that need generated study text (e.g. 64 cards): - Write a standalone script under scripts/ - Use OpenRouter chat completions with a strict JSON prompt - Request fields like: - overview - judgment - image - mnemonic - Save incrementally after each item so long runs can recover - Strip fenced code blocks before JSON.parse() because models may still return ```json wrappers - Merge generated JSON into the main dataset at import time rather than hardcoding everything in one file

Recommended data merge pattern

• Keep structural base data in src/data/hexagrams.ts
• Keep generated copy in src/data/...generated.json
• Import the generated JSON and map by ID/number onto the base dataset
• Include generated JSON in git if the app should work without rerunning generation

Deployment pattern

• Build with: tsc -b || true && vite build
• Always verify dist/assets/index-*.js modify timestamp changed
• Run server with PM2 on a single port
• nginx should proxy the subdomain directly to that one port
• For a PWA, do NOT enable nginx basic auth — installed PWAs break under basic auth

Verification checklist

• npm test
• npm run build
• Verify dist timestamp
• curl http://127.0.0.1:PORT/api/health
• curl -I http://127.0.0.1:PORT/sw.js and confirm no-cache headers
• Open the live app in browser tools and confirm:
• minimal top bar
• no redundant bottom controls
• gesture toast appears for first use
• flip works
• tiny glyph visuals actually render on the back of the card

Pitfalls

• Tiny compact glyphs may technically exist but be too subtle to notice; increase contrast/size and give them their own small panel if needed.
• OpenRouter may wrap JSON in markdown code fences; always clean before parsing.
• If PM2 says Use --update-env to update environment variables, restarting alone won’t refresh changed env vars.
• Browser text snapshots may miss subtle visual details; use screenshot/vision verification when checking tiny glyphs or minimalist UI polish.