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