# 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