Proposal: 3 Core Flow Docs + CLAUDE.md Operational Playbook for AI-Agent-Safe Flutter Changes

[beastoin]

Proposal: Rescope Omi App Documentation to 3 Core Flow Docs + CLAUDE.md Operational Playbook

Motivation

The current analysis confirms we have enough signal to simplify the documentation strategy without losing engineering safety.

From the 4 deep-analysis artifacts:

• UI flow mapping already spans 108 screens across core app flows (onboarding, home/conversations, chat, action items, memories, apps, settings, sync, payments).
• State composition is dense: lib/main.dart has 41 provider registrations with 9 proxy providers.
• Coupling risk is high: 49 page files import backend API clients directly.
• Provider blast radius is concentrated: AppProvider (31 files), HomeProvider (22), CaptureProvider (19), ConversationProvider (19), DeviceProvider (18).
• Dataflow trace covers end-to-end chains for chat, capture, processing, app install, action items, device connection, auth, and deep links.
• API surface is large (lib/backend/http/api: 24 modules, ~132 unique endpoint path patterns found by scan).
• Websocket event surface is non-trivial (MessageEvent includes 13 typed events + unknown fallback).
• Missing-flow audit found 19 additional dimensions (P0/P1/P2), but manager direction is clear: these should be operational guidance in CLAUDE.md, not separate flow docs.

This proposal keeps only the three docs needed for mobile dev best practice: UI flow + data flow + state management.

Proposal Summary

Create exactly 3 durable flow docs and move all other operational guidance into app/CLAUDE.md.

Also add one explicit governance rule to both CLAUDE.md and AGENTS.md:

Any PR with significant app changes MUST update the corresponding flow doc

---

Deliverable 1: UI Flow Doc

File

• app/docs/flows/ui-flow.md

Scope (in)

• Screen registry: screen name, class, file path, owner flow.
• Navigation graph: entry points, outbound edges, deep-link landings.
• Shared component map at flow level (not every widget).
• Code-file mapping for each screen (lib/pages/** + key lib/core/** route handlers).

Scope (out)

• API payload semantics.
• Provider mutation internals.
• Detailed error/retry logic.

Format

• Human doc: Markdown tables by flow.
• Generated artifact: YAML screen index for machine diffing.
  • app/docs/flows/generated/ui-flow.screens.yaml

Freshness Rule

• Mandatory update when PR changes navigation or screen behavior in:
  • lib/pages/**
  • lib/core/app_shell.dart
  • lib/pages/home/page.dart
• Generation script:
  • app/scripts/agent/generate_ui_flow_index.sh

Size Estimate

• 108 screens (current mapped baseline).
• ~10 major flow groups.
• ~12 deep-link/notification entry patterns currently documented.

---

Deliverable 2: Data Flow Doc

File

• app/docs/flows/data-flow.md

Scope (in)

• API call chains by feature flow (request -> transform -> provider -> UI).
• Model transformations (backend/schema to provider/UI usage).
• Websocket open/listen/dispatch paths.
• Error and fallback paths (including silent-fail and drift-risk points).

Scope (out)

• UI layout/component hierarchy.
• Provider dependency tree internals (that belongs to state doc).

Format

• Human doc: Markdown step tables per flow.
• Generated artifact: YAML inventories for endpoints/events/errors.
  • app/docs/flows/generated/data-flow.inventory.yaml

Freshness Rule

• Mandatory update when PR changes:
  • lib/backend/http/api/**
  • lib/backend/schema/**
  • lib/services/sockets/**
  • deep-link handlers in lib/core/app_shell.dart / lib/services/notifications.dart
• Generation script:
  • app/scripts/agent/generate_data_flow_inventory.sh

Size Estimate

• 24 API client modules.
• ~132 endpoint path patterns in current API code.
• 13 typed websocket events (+ unknown fallback).
• 8 primary end-to-end flows already traced and ready to formalize.

---

Deliverable 3: State Management Doc

File

• app/docs/flows/state-management.md

Scope (in)

• Provider tree from composition root.
• Mutation ownership per provider (source of truth fields + mutators).
• Blast-radius table (who depends on whom).
• Provider-to-provider chains (ProxyProvider + runtime cross-provider reactions).

Scope (out)

• API request payload details.
• Per-screen visual navigation details.

Format

• Human doc: Markdown tables (provider contract + blast radius).
• Generated artifact: YAML provider graph.
  • app/docs/flows/generated/state-management.providers.yaml

Freshness Rule

• Mandatory update when PR changes:
  • lib/main.dart provider registrations
  • lib/providers/**
  • provider files under lib/pages/**
• Generation script:
  • app/scripts/agent/generate_state_graph.sh

Size Estimate

• 41 provider registrations with 9 proxy providers in root tree.
• 30+ provider implementations (lib/providers + page-scoped providers).
• Initial blast-radius focus on top 5 high-impact providers.

---

What Goes in app/CLAUDE.md (Not Separate Docs)

These become sections in one operational playbook:

1. Build bootstrap

• Generated prerequisites (firebase_options_*, env/*.g.dart), flavors, local setup sequence.

2. Native bridge gotchas

• MethodChannel catalog + Pigeon contract rules (lib/watch_interface.dart / generated files).

3. Permission matrix

• Feature x platform x permission quick-reference table.

4. Test strategy

• Commands and required test depth by change type (UI-only, provider/state, API/data, native bridge).

5. L10n rules

• context.l10n requirement, ARB update workflow, regeneration command.

6. Security notes

• Auth token lifecycle, 401 retry/signout behavior, transport cautions.

7. Codegen rules

• Regeneration triggers/order; explicit “do not edit generated files” policy.

---

Governance Update (CLAUDE.md + AGENTS.md)

Add this exact rule:

Any PR with significant app changes MUST update the corresponding flow doc

Operational meaning:

• Navigation/screen changes -> update ui-flow.md
• API/schema/websocket/deeplink changes -> update data-flow.md
• Provider tree/mutations/dependencies changes -> update state-management.md

---

Concrete File Plan

Create

• app/docs/flows/ui-flow.md
• app/docs/flows/data-flow.md
• app/docs/flows/state-management.md
• app/docs/flows/generated/ui-flow.screens.yaml
• app/docs/flows/generated/data-flow.inventory.yaml
• app/docs/flows/generated/state-management.providers.yaml
• app/scripts/agent/generate_ui_flow_index.sh
• app/scripts/agent/generate_data_flow_inventory.sh
• app/scripts/agent/generate_state_graph.sh
• app/CLAUDE.md

Modify

• app/AGENTS.md (add mandatory update rule + pointers to 3 docs)
• app/README.md (add “Flow Docs” section linking the 3 docs)

---

Estimated Effort

• Phase 1: structure + scripts scaffolding + governance rules: 1.0–1.5 days
• Phase 2: seed all 3 docs with current known baseline from existing analysis: 1.5–2.0 days
• Phase 3: CI/doc freshness check + polish pass: 0.5 day

Total: 3–4 working days for an initial production-ready baseline.

---

Discussion Questions

1. Should we enforce freshness in CI immediately, or start with PR checklist enforcement for 2 weeks?
2. Do we want strict YAML schema validation for generated artifacts in Phase 1?
3. Should state-management.md include all providers now, or only top blast-radius providers first and expand incrementally?
4. Should data-flow.md track all endpoint patterns now, or focus on the 8 critical user journeys and expand by churn?

[hugoaap-code]

Time to make this professionally