rely/docs/PROGRESS.md

# Relationship Saver Progress Log

Updated: 2026-02-14

## 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. Wire `BackendGateway` into app services/use cases (not UI widgets directly).
2. Add session state provider (signed in / expired / signed out).
3. Add explicit offline indicators and non-blocking sync status UI.
4. Start consuming fake gateway in feature screens before live backend.

### 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>`