goose 17efc4f656 docs: reconcile documentation with reality (P3)

Make the project's documentation match the code and remove the sprawl. The docs
claimed Phase 2.8 (drug interactions) was 'planning/0%' and the backend '~91%
complete' — both wrong: 2.8 is implemented and live, plus the P0/P1 security
and test work is done. Five root CI/CD docs described a 'docker-build' CI job
that was removed; ~18 backend/ status snapshots and ~24 docs/implementation
duplicates cluttered the tree.

Deletions (85 files):
- Root: 4 stale CI/CD reports (CI-CD-{COMPLETION-REPORT,IMPLEMENTATION-SUMMARY,
  STATUS-REPORT,FINAL-STATUS}.md) — all describe the removed docker-build job.
- backend/: 18 phase/build/fix snapshots and code-dump .txt files.
- docs/: the 3 one-time reorg reports; ~17 docs/implementation duplicates and
  process artifacts; 4 stale docs/development CI docs + git snapshots;
  redundant deployment/testing files.
- thoughts/: STATUS.md (said Phase 2.4 in-progress), superseded phase notes and
  duplicative research inputs. tmp/ (928KB of CI debug logs, gitignored).

Moves (18 files):
- 9 genuine decision records -> docs/adr/ (Architecture Decision Records),
  date-prefixes stripped, with an index README.
- 8 historical-but-valuable phase plans/specs + the old CI-CD-FINAL-SOLUTION ->
  docs/archive/ (now-populated, with a README explaining it's superseded
  material). thoughts/ tree removed.

Rewrites (13 files) to match reality:
- Drop the fake '% complete' figures everywhere in favor of Implemented /
  In-Progress / Planned with concrete endpoint/feature lists.
- Phase 2.8 -> Implemented; add /api/interactions/* and /api/auth/{refresh,
  logout} to the endpoint lists; fix 'Rust 1.93' -> edition 2021.
- Add a Security section (token_version validation, hashed refresh-token
  persistence, fail-fast config, real-IP audit) and correct the test-coverage
  and deployment claims to reality.
- New canonical docs/development/CI-CD.md (4 jobs: format/clippy/build/test,
  mongo service, no docker-build + why).
- README, docs/README, product/{STATUS,ROADMAP,PROGRESS,README,introduction},
  implementation/README, development/README, testing/README, AI_AGENT_GUIDE,
  .cursorrules, .gooserules all updated.

Verified: greps for 'Phase 2.8 (Planning)', 'PLANNING (0%)', 'Rust 1.93',
'91%/10%/85% complete', and 'docker-build' return nothing outside docs/archive;
all internal doc links resolve; backend/src untouched (cargo build clean).

2026-06-27 16:02:16 -03:00

2.4 KiB

Raw Blame History

State Management Decision Summary

Date: 2026-02-14 Decision: Redux Toolkit 2.x

Scorecard

Criterion	Redux Toolkit	Zustand	Jotai	Weight
Code Sharing	10	10	10	Critical
Bundle Size	7	10	10	Critical
TypeScript	10	10	10	Critical
Complex State	10	7	5	Critical
Offline Sync	10	7	5	Critical
Weighted Score	9.2	8.6	7.6	-

Decision: Redux Toolkit 2.x

Score: 9.2/10

Key Advantages

Best for Complex State
- Family structure, multi-person profiles, permissions
- Built-in normalization (createEntityAdapter)
- Predictable state updates
- Time-travel debugging
Best for Offline Sync
- RTK Query for server state management
- Optimistic updates
- Background sync support
- Battle-tested offline patterns
Best Ecosystem
- Largest ecosystem
- Most resources, tutorials, examples
- Most production deployments
- Easiest to hire developers
Best Developer Experience
- Time-travel debugging
- Predictable state updates
- Easy to debug

Trade-offs

More boilerplate: More code, but clearer structure
Steeper learning curve: More concepts, but better patterns
Larger bundle: 60KB vs 3KB (negligible impact on 50-100MB app)

Technology Stack

Shared (Monorepo)

State Management: Redux Toolkit 2.x
Data Fetching: RTK Query 2.x
Async Thunks: createAsyncThunk
Persistence: Redux Persist 6.x
Selectors: Reselect 5.x
DevTools: Redux DevTools

Alternative Considered: Zustand

Score: 8.6/10

Why Redux Toolkit wins:

Better for complex state (family structure)
Better for offline sync (RTK Query)
Larger ecosystem (more resources)

When to use Zustand instead:

If team has no Redux experience
If state is simpler (no family structure)
If development speed is more important

Next Steps

Implement Redux Toolkit POC
Create family structure state slice
Implement RTK Query for server state
Test offline synchronization
Test encrypted data caching
Make final decision

Implementation Timeline

Setup Redux Toolkit: 1 day
Create state slices: 2-3 days
Implement RTK Query: 2-3 days
Implement offline sync: 3-5 days
Test encrypted caching: 2-3 days
Evaluate DX: 1-2 days

Total: 11-17 days (2-3 weeks)

2.4 KiB Raw Blame History