Alouwato

Architecture

Alouwato is a single-page Vue 3 app with no router and no backend, ported faithfully from a Claude Design prototype and keeping that prototype's single-store shape. All logic lives in one reactive store, split by concern. A core module owns the state singleton, a React-style setState, and versioned localStorage persistence: a schema version is stamped into every payload, and hydration replays an ordered chain of idempotent migrations, added after an early change turned a vision from a bare string into an object and survived reloads in the wrong shape. A context module derives once per render everything the screens share; fifteen domain builders each assemble one slice of a single render map that mixes derived data with inline event handlers, which components read and bind directly. The domain model is the part I designed: vision, then milestone (shared across visions through a list of ids), then task, and, kept deliberately separate, the session, which is the only thing that counts time, either a started block on the weekly grid or an on-the-fly activity. Ending a session appends a record to a journal, and the weekly review, the focus heatmap and the week/month/year long-view are all pure derivations of that journal. The data model is guarded by type-checking the store with JSDoc typedefs in CI. Delivery was disciplined: one issue per branch per pull request across eight milestones, a CI gate (lint, format, type-check, tests, build), a Playwright critical-path test, and a visual-regression harness of 118 reference screens across mobile and desktop, light and dark. It ships as an installable PWA on Vercel with no environment variables.

Engineering challenges

• Keeping persisted data safe across schema changes with no server to run a migration: every payload carries a schema version, and hydration replays an ordered chain of idempotent migration steps, so a shape change is explicit rather than a silently dropped key.
• Making "where did my time go" trustworthy: instead of storing running totals, the app archives each finished session to a journal and derives every review from it, so a reload or a re-plan never rewrites what was already lived.
• Not letting a faithful UI port drift as I made it functional: I froze the current app as 118 reference screenshots across mobile/desktop and light/dark and compared against them after every change, re-baselining only the intended ones.
• A milestone that genuinely belongs to several goals: a step carries a list of vision ids, so ticking it advances every river it feeds, and cutting one vision removes just that id instead of orphaning the step.

Technical decisions

• localStorage as the source of truth rather than a hosted database: the app had to work with no account and no network from the first launch, and the durable slice is small enough that a versioned JSON blob with file export and import covers backup.
• One reactive store with a render map rather than Pinia or component-local state: the app is a port of a prototype built that way, and keeping the shape made the port faithful and put the logic in one place that is cheap to test (most of the roughly 305 tests hit the store directly).
• Type-checking JavaScript with JSDoc rather than migrating to TypeScript: the real risk was shape drift in persisted data, not general type safety, so checking the store only caught what mattered without converting the whole codebase.
• No self-hosted auth even though the prototype showed Google, email and one-time-code sign-in: for a single-user personal tool a real backend adds an account to manage and a server to run for no benefit, so authentication and the PIN lock are local only (the PIN is a salted SHA-256 hash with a progressive lockout, not a login).