Rijad Zuzo
125 lines
3.9 KiB
Markdown
125 lines
3.9 KiB
Markdown
# Implementation Playbook
|
|
|
|
This guide shows how to add features without breaking the current architecture.
|
|
|
|
## General Workflow
|
|
|
|
1. Read the slice README.
|
|
2. Identify whether the behavior is domain, application, presentation, or
|
|
repository state.
|
|
3. Add or change the feature-owned model.
|
|
4. Update `LocalDataState` only if a new persisted collection is needed.
|
|
5. Route all writes through `LocalRepository`.
|
|
6. Add focused tests.
|
|
7. Update docs when behavior changes across slices.
|
|
|
|
## Example Feature: Add A New Captured Fact Type
|
|
|
|
Suppose you want shares and manual capture to support a new fact type:
|
|
`communicationStyle`.
|
|
|
|
### Files To Change
|
|
|
|
Domain:
|
|
|
|
- `lib/features/share_intake/domain/share_models.dart`
|
|
- add enum value to `CapturedFactType`
|
|
- `lib/features/people/domain/person_models.dart`
|
|
- ensure any switch over `CapturedFactType` handles the new value
|
|
|
|
Extraction and suggestions:
|
|
|
|
- `lib/features/share_intake/domain/share_capture_draft_suggester.dart`
|
|
- `lib/core/llm/llm_service.dart`
|
|
- `lib/core/llm/captured_fact_draft_parser.dart`
|
|
|
|
Persistence:
|
|
|
|
- `lib/app/data/relationship_repository_share.dart`
|
|
- ensure `_applyFactDraftToFacts` stores the new type correctly
|
|
- `lib/app/state/local_data_state.dart`
|
|
- usually no change needed because facts already store `CapturedFactType`
|
|
|
|
UI:
|
|
|
|
- `lib/features/share_intake/presentation/share_capture_review_sheet.dart`
|
|
- `lib/features/share_intake/presentation/share_inbox_view.dart`
|
|
- `lib/features/people/presentation/people_view_detail.dart`
|
|
|
|
AI digest:
|
|
|
|
- `lib/features/ai_digest/application/anonymized_llm_context_builder.dart`
|
|
- update `_factTypeLabel`
|
|
|
|
Tests:
|
|
|
|
- `test/features/share_intake/share_capture_draft_suggester_test.dart`
|
|
- `test/core/llm/captured_fact_draft_parser_test.dart`
|
|
- `test/features/local/local_repository_test.dart`
|
|
- `test/features/ai_digest/anonymized_llm_context_builder_test.dart`
|
|
|
|
### Rules
|
|
|
|
- Add enum values at the end unless there is a strong reason to reorder.
|
|
- Keep `fromJson` fallback behavior.
|
|
- Add tests for unknown or missing values when changing parsing behavior.
|
|
- Do not make LLM output the only way to create the new type. Provide a local
|
|
fallback or review UI path.
|
|
|
|
## Example Feature: Add A New Share Source Parser
|
|
|
|
Suppose you want better Telegram parsing.
|
|
|
|
Files:
|
|
|
|
- Add `lib/features/share_intake/domain/telegram_share_parser.dart`.
|
|
- Update `SharePayloadParser._normalizeSourceApp`.
|
|
- Update `SharePayloadParser._parseSourceMetadata`.
|
|
- Add tests in `test/features/share_intake/`.
|
|
|
|
Parser expectations:
|
|
|
|
- Return message text without source prefix noise.
|
|
- Extract display name only when the pattern is strong.
|
|
- Extract stable source IDs only when they are provided by the source.
|
|
- Leave unknown timestamps null.
|
|
- Never throw on malformed input.
|
|
|
|
Repository expectations:
|
|
|
|
- Exact identity match can auto-link only when unambiguous.
|
|
- Near matches should route to Share Inbox.
|
|
- Source profile links should be stable across follow-up shares.
|
|
|
|
## Example Feature: Sync A New Entity
|
|
|
|
Suppose AI suggestion drafts need REST sync.
|
|
|
|
Files:
|
|
|
|
- `docs/api/openapi.yaml`
|
|
- `lib/integrations/backend/models/backend_models.dart`
|
|
- generated backend model files
|
|
- `lib/integrations/backend/backend_gateway_rest.dart`
|
|
- `lib/integrations/backend/backend_gateway_fake.dart`
|
|
- `lib/integrations/backend/sync_envelope_validator.dart`
|
|
- `lib/app/data/relationship_repository_ai_digest.dart`
|
|
- tests under `test/integrations/backend` and `test/features/sync`
|
|
|
|
Design choices to document:
|
|
|
|
- entity type string in `ChangeEnvelope`
|
|
- create/update/delete semantics
|
|
- conflict behavior
|
|
- whether rejected changes are user-repairable
|
|
- privacy implications
|
|
|
|
## Review Checklist Before Shipping
|
|
|
|
- `flutter analyze`
|
|
- focused tests for touched slices
|
|
- full `flutter test` when practical
|
|
- manual Settings smoke test for config/debug actions
|
|
- manual share simulation test after share changes
|
|
- physical-device test after native share, notification, or background changes
|