Lightweight records of significant design decisions with context and consequences.
Each ADR documents a significant design decision, capturing the forces at play, the decision made, and its tradeoffs. ADRs are immutable once accepted—supersede rather than modify.
| ADR | Title | Status |
|---|---|---|
| 001 | Static-first with edge API | Accepted |
| 002 | Three fixed categories | Accepted |
| 003 | localStorage before backend | Accepted |
| 009 | Multi-provider OAuth | Accepted |
| 011 | Custom auth (not Auth.js) | Accepted |
| 013 | Duplicate detection for imports | Accepted |
| 014 | Percentage-based allocation | Accepted |
| 015 | noUiSlider for allocation UX | Accepted |
| 016 | Dual-column allocation board | Accepted |
| 017 | Payment method purge | Accepted |
| 019 | JWT Bearer tokens | Accepted |
| 020 | Cloudflare Pages previews | Accepted |
| 021 | Auth button visibility | Accepted |
| 022 | Product repositioning | Accepted |
| 023 | Cloud sync integration | Accepted |
| 024 | Storage mode selection | Accepted |
| 025 | Onboarding wizard | Accepted |
| 026 | Disclaimer visibility/export attribution | Accepted |
| 027 | Validation gate stabilization | Accepted |
| 028 | Cloud-intent data authority hotfix | Accepted |
| 029 | Explicit storage-intent/session-state/data-authority model | Accepted |
| 030 | Local identity, local sign-out, and encrypted vault decision | Accepted |
| 032 | Entity type configuration and tax warnings | Accepted |
ADRs 001–018 are archived in DESIGN-archive.md. Recent ADRs (019+) have individual files.
How to use: Before modifying code mentioned in "Used By" column, read "Depends On" ADRs to understand constraints.
| ADR | Title | Depends On | Used By | Conflict Risk |
|---|---|---|---|---|
| 019 | JWT Bearer Tokens | 009 (OAuth) | 023 (Cloud Sync), worker/src/session.js | None |
| 020 | CF Pages Previews | 001 (Static-first) | Deployment workflow, scripts/deploy-preview.sh | Low |
| 021 | Auth Button Visibility | 009 (OAuth) | 025 (Onboarding), index.html:auth-section | High (UI coordination) |
| 022 | Product Repositioning | None | Marketing copy, DESIGN.md, README.md | None |
| 023 | Cloud Sync Integration | 003 (localStorage-first), 019 (JWT) | js/storage.js, worker/src/expenses.js | Medium (sync conflicts) |
| 024 | Storage Mode Selection | 003, 023 | 025 (Onboarding), js/app.js:storageIntent | None |
| 025 | Onboarding Wizard | 024, 021 | index.html:wizard, js/app.js:showNav | High (modifying showNav breaks onboarding flow) |
| 029 | Explicit State Model | 024, 028 | js/app.js, js/app-storage.js, tests/state-model.spec.js | High (data authority gates) |
| 030 | Local Identity and Sign-Out | 024, 029 | index.html, js/app-identity.js, tests/local-signout.spec.js | High (shared-device security UX) |
| 032 | Entity Type Configuration | 003 (localStorage) | js/app-settings.js, js/app.js, index.html:settings | Low |
Conflict risk levels:
- High: Changes require coordinating across multiple files; test extensively
- Medium: Changes may require sync logic updates or conflict resolution
- Low: Changes isolated to specific subsystem
- None: Changes don't affect other ADRs
# ADR-NNN: Title
**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Deprecated | Superseded
## Context
What is the issue? What forces are at play?
## Decision
What is the change proposed?
## Consequences
What becomes easier? What becomes harder?