This commit is contained in:
Rijad Zuzo
@@ -0,0 +1,124 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user