rely/docs/IMPLEMENTATION_PLAYBOOK.md

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