Architecture

• What are the independent units?
• What are their responsibilities?
• How do they communicate?
• What are the dependencies?

3. Define Boundaries

• Each component has ONE clear responsibility
• Communication through well-defined interfaces
• Components can be understood and tested independently
• Changes in one component don't cascade to others

4. Data Flow

• Where does data originate?
• How does it transform through the system?
• Where is it stored?
• Who can read/write it?

5. Evaluate Trade-offs

• Simplicity vs. flexibility
• Performance vs. maintainability
• Consistency vs. availability
• Build vs. buy

Architecture Patterns (Flutter/Firebase)

Feature-Based Architecture

lib/features/<feature>/
  ├── data/          # Repositories, data sources
  ├── domain/        # Models, business logic
  └── presentation/  # Screens, widgets, state

State Management

• Provider/Riverpod for dependency injection and reactive state
• Streams for real-time Firestore data
• ValueNotifier for simple local state

Data Layer

• Repository pattern — abstract data source from business logic
• Firestore collections — design for query patterns, not normalization
• Offline-first — local cache with sync

Navigation

• GoRouter for declarative routing
• Deep links validated at entry point
• Role-based routing — guards enforce access

Design Principles

Red Flags

• God class/file — one file doing too much (>300 lines is a smell)
• Circular dependencies — A depends on B depends on A
• Leaky abstractions — implementation details exposed through interfaces
• Shotgun surgery — one change requires touching many files
• Feature envy — a component using another component's data more than its own

Document Decisions

For significant architecture decisions, document:

• Context — what prompted the decision
• Decision — what was chosen
• Consequences — what trade-offs were accepted
• Alternatives — what was considered and rejected