# Research — GlowTrack

## Decisions
- Framework: SvelteKit + TypeScript with `@sveltejs/adapter-static` (no backend)
- Storage: IndexedDB via `idb`; JSON import/export with versioning
- Visualization: Lightweight Canvas/SVG hybrid renderer optimized for mobile
- Styling: Tailwind CSS with CSS variables; color-blind friendly palettes
- Accessibility: Target WCAG AA; keyboard-first interactions
- PWA: SvelteKit service worker with minimal runtime cache for full offline
- Tooling/Reproducibility: Nix flake provides devShell and build
- CI: Nix build + Vitest unit tests + Playwright smoke tests
- Hosting: GitHub Pages or Netlify (static hosting) from Nix build output

## Rationales
- SvelteKit offers SSR/SSG flexibility and first-class PWA support while remaining light for static export
- `idb` simplifies IndexedDB usage and supports versioned migrations for local-first data
- Canvas/SVG hybrid provides high-performance drawing with crisp glyph overlays and accessibility-friendly fallbacks
- Tailwind accelerates consistent UI while CSS variables enable theming and low-cost runtime adjustments
- Keeping everything client-side preserves privacy and enables offline-by-default usage
- Nix ensures reproducible dev environments and CI builds across machines

## Alternatives Considered
- React/Vite: viable but SvelteKit yields smaller bundles and simpler reactivity
- LocalStorage/WebSQL: insufficient for structured data and migrations; IndexedDB preferred
- Pure Canvas or pure SVG: hybrid approach chosen to balance performance with resolution-independent elements
- Service worker libraries (e.g., Workbox): SvelteKit’s built-in SW is sufficient given minimal caching needs

## Open Questions (Resolved by requirements/spec)
- Export format: PNG at screen resolution for sharing/wallpaper
- Sharing: JSON export/import only; no hosted links or image sharing by app
- Tile visual rules: Base hue by mood; net habit score controls luminance; negative = static overlay; glyph counts

---

## Additional Research Backlog (Prioritized)

1) Canvas/SVG performance on mobile (P1)
- Goal: 60 fps for 150–365 tiles with glow/overlay; define rendering budget and fallbacks
- Deliverable: Benchmark results, thresholds, viz package notes
- Method: Build FPS harness; test mid/low-end Android + iOS

2) IndexedDB schema + import/migration performance (P1)
- Goal: Reliable imports for multi-year datasets; smooth migrations; responsive UI
- Deliverable: Import chunk size, transaction strategy, migration template, storage footprint
- Method: Seed 3-year dataset; time import/migration; measure DB size/quota

3) Accessibility palettes and glyph legibility (P1)
- Goal: WCAG AA contrast; color-blind safe palettes; legible glyphs at small sizes
- Deliverable: Approved palettes, CSS vars, glyph sizing spec
- Method: Simulators + Axe checks; user testing if possible

4) PWA SW update + offline write safety (P1)
- Goal: Safe app update with pending writes and schema changes
- Deliverable: SW update policy, cache versioning, migration + rollback checklist
- Method: Offline simulation during schema bump; verify no data loss

5) PNG export fidelity and limits (P2)
- Goal: Fast, reliable PNG export with crisp glyphs; cap size to prevent OOM
- Deliverable: Use toBlob/toDataURL guidance, max dimensions, UX for progress/errors
- Method: Export month/year grids; measure time/memory/file size

6) Keyboard-first grid navigation + SR UX (P2)
- Goal: Intuitive keyboard nav with correct ARIA; SR speaks mood and counts
- Deliverable: Roving tabindex model, ARIA roles/labels, SR strings
- Method: Prototype navigation + Playwright+Axe tests

7) Tailwind + CSS variables theming (P2)
- Goal: Minimal CSS output with dynamic theming; safe class generation
- Deliverable: Theming tokens and example; purge-safe patterns
- Method: Prototype theme switcher; inspect bundle size

### Active Research Tasks (links)
- 01: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/01-viz-performance.md
- 02: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/02-indexeddb-imports-migrations.md
- 03: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/03-a11y-palettes-glyphs.md
- 04: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/04-pwa-sw-offline-safety.md
- 05: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/05-png-export-fidelity.md
- 06: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/06-keyboard-sr-grid.md
- 07: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/07-tailwind-css-vars.md