docs: add project orientation notes

2026-05-17 00:17:03 +02:00
parent 6c4a139448
commit dab50abf0e
6 changed files with 701 additions and 12 deletions
@@ -0,0 +1,173 @@
+# 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