# Relationship Saver Progress Log

Updated: 2026-02-15

## Latest Milestone (2026-02-15): Local Persistence + CRUD Baseline

Implemented the first real local data foundation pass (replacing static demo-only reads):

- Added persisted local state using `shared_preferences`:
  - `lib/features/local/local_repository.dart`
  - schema key/version scaffold + seed fallback + persistence logic
- Upgraded local models with serialization/copy methods:
  - `lib/features/local/local_models.dart`
- Added local CRUD operations:
  - people: add, edit, delete
  - moments: add, delete
  - dashboard tasks: done/undone toggle
- Wired views to async persisted state:
  - `DashboardView`, `PeopleView`, `MomentsView`
- Updated signals fallback to read from persisted local state:
  - `lib/features/signals/signals_controller.dart`
- Added local repository tests:
  - `test/features/local/local_repository_test.dart`

Validation for this milestone:

- `flutter analyze` -> pass
- `flutter test` -> pass

## Workflow Rule

- After every sensible change, the final step is a Git commit with a clear message.
- Keep changes in small, logical commits so future sessions can revert or continue safely.

## Latest Milestone (2026-02-15): Product UI Flow Implemented

The app now has a real multi-screen user experience on macOS (and other platforms), not just a placeholder screen.

Delivered UI architecture:

- App shell with responsive navigation:
  - desktop: left sidebar + content pane
  - compact: bottom navigation (reduced to 4 primary tabs)
  - compact secondary actions (`Sync`, `Settings`) moved into a `More` menu to avoid tab overload on iOS/mobile
- Views implemented:
  - Dashboard
  - People
  - Moments
  - Signals
  - Sync
  - Settings
- Reference-aligned visual style:
  - WorkSans typography (copied from the UI reference assets)
  - soft gradients, rounded glass-like cards, accent palette similar to the reference repo
- Offline-safe UX:
  - fake backend mode now defaults to `true` unless overridden via `--dart-define=USE_FAKE_BACKEND=false`
  - signals view gracefully falls back to local recommendations when backend calls fail

Key new files:

- `lib/features/home/app_shell.dart`
- `lib/features/dashboard/dashboard_view.dart`
- `lib/features/people/people_view.dart`
- `lib/features/moments/moments_view.dart`
- `lib/features/signals/signals_controller.dart`
- `lib/features/signals/signals_view.dart`
- `lib/features/sync/sync_view.dart`
- `lib/features/settings/settings_view.dart`
- `lib/features/shared/frosted_card.dart`
- `lib/features/local/local_models.dart`
- `lib/features/local/local_repository.dart`
- `assets/fonts/WorkSans-*.ttf`

Other updates:

- `lib/main.dart` now launches the new app shell.
- `lib/core/config/app_theme.dart` updated to a stronger visual system.
- `pubspec.yaml` includes local WorkSans font family.
- `test/widget_test.dart` updated for the new flow.

Validation status after UI milestone:

- `flutter analyze` -> pass
- `flutter test` -> pass

## Current Gap Analysis (2026-02-15)

### What we have now

- Backend gateway architecture with REST + fake implementations, typed DTOs, retries, refresh, and tests.
- OpenAPI + ADR documentation baseline.
- Product UI shell with responsive desktop/mobile navigation and key views.
- Offline-safe default behavior with fake backend mode.

### What is still missing

- Local database persistence and repository wiring (currently demo in-memory data).
- Full CRUD flows (create/edit/delete) for people, captures, reminder rules, gift/event ideas.
- Auth UX flows (sign-in, session-expired recovery, sign-out confirmation).
- Real sync orchestration layer (queue, cursor lifecycle, conflict policy UI).
- Notifications/reminders delivery and scheduling integration.
- End-to-end and integration tests for app flows beyond unit/widget basics.

## Implementation Plan (Next)

### Phase 1: Data Foundation

1. Introduce local DB schema + repository interfaces for core entities.
2. Replace `LocalRepository` demo data with persisted data access.
3. Add migration/test coverage for DB reads/writes.

### Phase 2: Core Product Flows

1. Build People CRUD and detail editing screens.
2. Build Moments/Captures create-and-list workflows.
3. Add Ideas and Reminder Rule management.

### Phase 3: Sync + Auth UX

1. Add sync queue service and cursor management use cases.
2. Add conflict handling strategy and UI states.
3. Implement sign-in/session lifecycle screens and provider state.

### Phase 4: Quality + Release Readiness

1. Add CI for analyze/test and optional build smoke checks.
2. Expand widget/integration tests for primary user journeys.
3. Add observability hooks and production hardening pass.

## Current Status

The Flutter app now includes a production-grade backend integration scaffold with an offline-first posture:

- Local/offline UX remains primary; backend is optional for core usage.
- A transport-agnostic gateway interface is in place.
- REST implementation with auth refresh/retry/error mapping is implemented.
- Deterministic fake gateway is available for local/dev without backend.
- OpenAPI contract + ADR + setup docs + unit tests are in place.
- `flutter analyze` and `flutter test` are passing.

## What Was Implemented

### 1. Core Config + Theme Shell

- Added backend config with build-time + runtime override:
  - `lib/core/config/app_config.dart`
- Added lightweight app theme aligned with reference style direction:
  - `lib/core/config/app_theme.dart`
- Updated app entry shell and Riverpod root:
  - `lib/main.dart`

### 2. Network Foundation

Implemented a Dio stack with request metadata, auth, refresh, retry, and error mapping:

- `lib/core/network/dio_factory.dart`
- `lib/core/network/network_constants.dart`
- `lib/core/network/backend_exception.dart`
- `lib/core/network/dio_error_mapper.dart`
- Interceptors:
  - `lib/core/network/interceptors/request_metadata_interceptor.dart`
  - `lib/core/network/interceptors/auth_interceptor.dart`
  - `lib/core/network/interceptors/refresh_token_interceptor.dart`
  - `lib/core/network/interceptors/retry_interceptor.dart`

Behavior implemented:

- Adds per-request `X-Request-Id`.
- Adds `Authorization: Bearer <token>` when session exists.
- On `401`, attempts one refresh (`/v1/auth/refresh`) then retries original request.
- If refresh fails, session is cleared and `AuthExpiredException` surfaced.
- Retry policy (max 2 retries, exponential backoff):
  - Retry transient failures (`timeouts`, `connection`, `5xx`).
  - Safe methods (`GET/HEAD/OPTIONS`) retry automatically.
  - Non-idempotent endpoints only retry when `Idempotency-Key` exists.
- Maps Dio failures into typed backend exceptions with metadata.

### 3. Auth Token Storage

- Interface:
  - `lib/core/auth/token_store.dart`
- Production implementation:
  - `lib/core/auth/secure_token_store.dart`
- Test/dev implementation:
  - `lib/core/auth/in_memory_token_store.dart`

### 4. Backend Integration Layer

Domain boundary and implementations:

- Interface:
  - `lib/integrations/backend/backend_gateway.dart`
- REST:
  - `lib/integrations/backend/backend_gateway_rest.dart`
- Fake:
  - `lib/integrations/backend/backend_gateway_fake.dart`
- Optional Riverpod providers:
  - `lib/integrations/backend/backend_gateway_provider.dart`
- Sync validation:
  - `lib/integrations/backend/sync_envelope_validator.dart`

Implemented methods:

- sign-in/out + me
- sync pull/push (with idempotency key on push)
- signals feed + ack
- upload init + download URL scaffold

Offline-first hardening:

- `signOut()` clears local token store in `finally`, even when network call fails.

### 5. Typed Models (Freezed + JSON)

- `lib/integrations/backend/models/backend_models.dart`
- Generated files:
  - `backend_models.freezed.dart`
  - `backend_models.g.dart`

Includes DTOs/enums for:

- Auth (`SignInRequest`, `AuthSession`, refresh request/response, `UserProfile`)
- Sync (`ChangeEnvelope`, push/pull requests/results, ack/rejection)
- Signals (`SignalsFeed`, `SignalItem`, ack request/action)
- Uploads (`UploadInitRequest/Result`, `DownloadUrl`)

### 6. Contract + Architecture Docs

- OpenAPI spec:
  - `docs/api/openapi.yaml`
- ADR:
  - `docs/ADR/0002-backend-protocol-rest-openapi.md`
- Setup instructions:
  - `docs/SETUP.md`
- Previous concise checklist log:
  - `docs/PROGRESS.md`

### 7. Tooling + Quality

- Strict analyzer/lints:
  - `analysis_options.yaml`
- Dependencies added in `pubspec.yaml`:
  - runtime: `dio`, `freezed_annotation`, `json_annotation`, `flutter_secure_storage`, `uuid`, `clock`, `flutter_riverpod`
  - dev: `freezed`, `json_serializable`, `build_runner`, `mocktail`

### 8. Test Coverage Added

Core network and model tests:

- `test/core/network/token_refresh_interceptor_test.dart`
- `test/core/network/dio_error_mapper_test.dart`
- `test/core/network/retry_interceptor_test.dart`
- `test/integrations/backend/backend_models_serialization_test.dart`
- `test/integrations/backend/sync_envelope_validator_test.dart`
- helper adapter: `test/helpers/queue_http_client_adapter.dart`
- updated smoke widget test: `test/widget_test.dart`

## Verification Snapshot

Most recent local checks:

- `flutter analyze` -> pass
- `flutter test` -> pass

## Known Gaps / Intentional Scope Limits

- No realtime transport yet (SSE/WebSocket intentionally deferred).
- No backend-generated client code from OpenAPI yet.
- No persistence layer wiring to local DB yet (gateway is ready to plug in).
- No UI features using backend gateway yet beyond app shell readiness.
- Fake gateway data is deterministic sample content, not scenario-configurable yet.

## Handoff Plan For Next Agent Sessions

### Priority 1: Repository Hygiene + CI

1. Add CI workflow for `flutter analyze` + `flutter test`.
2. Add branch protections / PR template if desired.
3. Keep generated files committed policy explicit in README.

### Priority 2: Local DB Integration (Offline-First Core)

1. Define local domain entities and repositories for `person`, `capture`, `giftIdea`, `eventIdea`, `tag`, `reminderRule`.
2. Map local mutations to `ChangeEnvelope` and enqueue for sync.
3. Create sync orchestrator service that:
   - pushes pending local mutations,
   - applies pull changes with conflict policy,
   - stores/advances cursor.
4. Add tests for conflict handling and cursor progression.

### Priority 3: App Wiring + UX

1. Replace local demo repository data with actual local DB repositories.
2. Add create/edit flows for people, captures, reminders, and ideas (forms + validation).
3. Add session state and auth entry screens (sign-in, expired-session recovery).
4. Add explicit offline badges and sync conflict resolution UI.

### Priority 4: Security + Hardening

1. Add central log redaction helper for headers/bodies.
2. Add token-expiry pre-check strategy (optional proactive refresh).
3. Evaluate secure storage behavior on web target and fallback policy.
4. Add tests for concurrent 401 refresh race conditions.

### Priority 5: API Evolution

1. Version strategy in OpenAPI (`/v1` already set).
2. Define backend error payload schema formally in OpenAPI.
3. Add capabilities endpoint for future realtime negotiation.
4. Add SSE/WebSocket design ADR when backend is ready.

## How To Continue Quickly

1. Run: `flutter pub get`
2. If models change: `dart run build_runner build --delete-conflicting-outputs`
3. Validate: `flutter analyze && flutter test`
4. Start from:
   - gateway surface: `lib/integrations/backend/backend_gateway.dart`
   - sync transport: `lib/integrations/backend/backend_gateway_rest.dart`
   - contract: `docs/api/openapi.yaml`

## Important Notes

- Current default base URL is placeholder (`https://api.example.com`).
- Use fake mode for local iteration:
  - `flutter run --dart-define=USE_FAKE_BACKEND=true`
- Build-time URL override:
  - `flutter run --dart-define=BACKEND_BASE_URL=<your-url>`