flutter-architecture-decisions

Flutter Architecture Decisions

Overview

Flutter Architecture Decisions provides a pragmatic framework for selecting one primary state management solution (Riverpod, Bloc/Cubit, Signals, or setState), drawing high-bar package boundaries, and recording concise MADR records (docs/<feature-name>/adr-NNN-*.md <= 55 lines) and conditional blueprints (the ## Architecture section of docs/<feature-name>/spec.md, <= 50 lines) across Claude Code and Google Antigravity.

When to Use

Trigger Scenarios

• Scaffolding a Flutter app, choosing/migrating state management, or introducing GoRouter/FFI/platform-channel topology shifts.
• Evaluating whether a domain boundary warrants a standalone Dart package vs. folder namespace.
• Resolving PR disputes on dependency direction across UI, Domain, and Data layers.

When NOT to Use

• Routine feature or single-widget work: When changes fit established repository architecture, skip creating redundant ADRs or ## Architecture content.
• Backend / non-Dart services: Use senior-architect-engineering or design-spec-expert.

Process

flowchart LR
    A["Inspect AGENTS.md & DESIGN.md"] --> B["State Matrix & Package Gate"]
    B --> C["Draft Concise MADR (<=55 lines)"]
    C --> D{"Multi-Layer / Package?"}
    D -->|"Yes"| E["Author spec.md ## Architecture (<=50 lines)"]
    D -->|"No"| F["Skip Redundant Blueprint"]

1. Align Layered Split & Root Contracts

Inspect root AGENTS.md (<= 90 lines wired to context/memory/MEMORY.md) and official Google root DESIGN.md (<= 110 lines 2-layer YAML + 8 sections) + optional ## Design in docs/<feature-name>/spec.md (<= 30 lines screen delta). Enforce clean UI (widgets/themes) -> Domain (use cases/entities) -> Data (repositories/DTOs/clients) separation.

2. State Management & High-Bar Package Gate

Evaluate state complexity via references/state-management-decision-matrix.md: pick one primary solution per app (setState for local ephemeral state). Extract a separate package only if >= 2 hold: reused across apps, decoupled release cadence, 1-sentence public API, and standalone test suite.