rely/docs/client-implementation-plan.md

# Client Implementation Plan

Date: 2026-04-01

## Chosen scope for this iteration

This iteration focuses on the smallest slice that materially improves founder
testing:

1. Generalize intake from WhatsApp-only text import to a broader shared payload
   pipeline that supports:
   - plain text
   - URL
   - text + URL
2. Add an explicit clarification flow for ambiguous shares:
   - assign to existing person
   - create person quickly
   - save to inbox for later
3. Improve the local person knowledge model with:
   - aliases
   - structured captured facts
   - important dates
   - timestamps
   - source/provenance metadata
4. Upgrade inbox triage so unresolved shares can be converted into:
   - note
   - like
   - dislike
   - important date
   - gift idea
   - place idea
   - activity idea
   - misc fact
5. Add trust-facing settings copy and targeted tests.

## Why this scope

- It directly improves the most important product workflow: fast capture from
  outside the app.
- It stays client-side and local-first.
- It does not require a storage rewrite or backend coupling.
- It produces data structures that future LLM/recommendation work can consume.
- It keeps risk contained by extending the existing repository and views rather
  than replacing them.

## Affected files / modules

### Expected to change

- `lib/main.dart`
- `lib/features/local/local_models.dart`
- `lib/features/local/local_repository.dart`
- `lib/features/people/people_view.dart`
- `lib/features/settings/settings_view.dart`
- `lib/features/share_intake/share_inbox_view.dart`
- `lib/features/share_intake/whatsapp_share_listener.dart` or replacement
- `android/app/src/main/AndroidManifest.xml`
- `test/features/local/local_repository_test.dart`
- `test/features/share_intake/share_inbox_view_test.dart`

### Expected to add

- generic share payload parser / models
- share review sheet / dialog component
- parser unit tests
- iteration summary doc

## Architecture decisions

### 1. Keep `LocalRepository` as the orchestration layer

Reason:
- It already owns local persistence, entity updates, and ingestion logic.
- Extending it is safer than introducing a second persistence coordinator.

Tradeoff:
- The file remains large.

Mitigation:
- Add focused helpers/models for share parsing and captured-fact typing rather
  than pushing more UI logic into the repository.

### 2. Add structured fact/date entities instead of overloading `notes`

Reason:
- Future recommendation features need provenance, timestamps, and type-safe
  context.
- Users need auditability and correction, not just a bigger notes blob.

Tradeoff:
- More model surface area now.

Mitigation:
- Keep entity types intentionally small and local-only for this iteration.

### 3. Prefer inbox-first safety over aggressive auto-assignment

Reason:
- Wrong person attachment is worse than extra triage work in this domain.

Decision:
- Only auto-assign when confidence is genuinely high.
- Otherwise open clarification UI or save to inbox.

### 4. Fix Android share entry now, defer iOS native extension

Reason:
- Android manifest support is low-cost and unblocks real testing.
- Proper iOS share extension work is native-project-heavy and should be treated
  as a separate scoped task.

## UX flows

### Flow A: direct share received with high-confidence target

1. Normalize incoming share into `SharedPayload`.
2. If a stable source link or clear unique alias/name match exists, allow direct
   save to the person.
3. Persist the payload history plus a structured fact defaulting to `note`
   unless a better classification is explicitly chosen.
4. Show confirmation snackbar and navigate to the relevant destination on cold
   start.

### Flow B: share received without safe target

1. Normalize into `SharedPayload`.
2. Open a lightweight review sheet when possible.
3. Offer:
   - recent people / candidate people
   - quick create person
   - save to inbox
4. If the user saves to inbox, persist payload + draft classification and leave
   the item unresolved.

### Flow C: inbox triage later

1. Open `Share Inbox`.
2. Review the preview text/URL and suggested candidates.
3. Choose person or create one.
4. Choose classification and edit the extracted content.
5. Save as structured fact/date.

## Risks

### Risk: model expansion causes migration issues

Fallback:
- Keep new JSON fields backward-compatible with defaults in `fromJson`.

### Risk: generic share parsing creates false confidence

Fallback:
- Default to inbox / manual clarification for unclear payloads.

### Risk: too much UI churn in `PeopleView`

Fallback:
- Add new review sections for facts/dates without reworking the whole people
  editor architecture.

### Risk: native plugin behavior differs across platforms

Fallback:
- Keep settings-based share simulation path for deterministic local testing.

## Intentionally deferred

- iOS share extension target creation and App Group setup
- image/file share support
- sync mapping for new fact/date entities
- AI-driven classification/recommendations
- full-text search across inbox/facts/dates
- notification engine hooks for new entities