skills/flutter-architecture/references/layers.md

# Architecture Layers

Detailed guide to layer responsibilities and interactions in Flutter apps.

## Layer Overview

```
┌─────────────────────────────────────┐
│           UI Layer                  │
│  ┌────────────┐  ┌─────────────┐ │
│  │   Views    │  │ ViewModels  │ │
│  └────────────┘  └─────────────┘ │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│      Domain Layer (Optional)        │
│       ┌─────────────────────┐      │
│       │     Use-cases       │      │
│       └─────────────────────┘      │
└─────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────┐
│          Data Layer                │
│  ┌────────────┐  ┌─────────────┐ │
│  │Repositories │  │  Services   │ │
│  └────────────┘  └─────────────┘ │
└─────────────────────────────────────┘
```

## UI Layer

Responsibility: Interact with user, display data, receive input.

### Views
**What they do:**
- Compose widgets to present data
- Handle user interactions (taps, form inputs)
- Pass events to ViewModel
- Re-render when ViewModel state changes

**What they don't do:**
- Business logic
- Data transformation
- State persistence
- API calls

**Logic allowed in Views:**
- Simple if-statements for conditional rendering
- Animation logic
- Layout logic (responsive design, orientation)
- Simple routing

### ViewModels
**What they do:**
- Transform repository data into UI state
- Maintain UI state (survives configuration changes)
- Expose commands for user actions
- Aggregate data from multiple repositories

**What they don't do:**
- Direct UI manipulation
- Platform API calls
- File I/O
- Network requests directly (use repositories)

**State management:**
- Use ChangeNotifier for simple apps
- Consider Provider, Riverpod, or Bloc for complex apps
- Expose state as Streams or ChangeNotifiers
- Call Repositories directly for simple flows; introduce Use-cases only when
  business logic is complex, reused, or spans multiple Repositories.

## Domain Layer (Optional)

**Purpose**: Abstract complex business logic from ViewModels.

### When to add Domain Layer
Add when ViewModels have logic that:
1. Merges data from multiple repositories
2. Is exceedingly complex
3. Will be reused by different ViewModels

### Use-cases
**What they do:**
- Take data from repositories
- Transform for UI layer consumption
- Encapsulate reusable business logic

**Relationships:**
- Use-cases depend on Repositories
- Use-cases and Repositories: many-to-many
- ViewModels may depend on Use-cases for complex operations and on Repositories
  directly for simple operations.

**Pros:**
- Avoid code duplication in ViewModels
- Improve testability by separating complex logic
- Improve code readability in ViewModels

**Cons:**
- Increases complexity
- Additional mocks for testing
- Adds boilerplate code

**Recommendation**: Add use-cases only when needed. Don't force all data access through use-cases for simple operations.

## Data Layer

Responsibility: Handle business data and logic.

### Repositories
**What they do:**
- Single source of truth for data types
- Poll data from Services
- Transform raw data into domain models
- Handle business logic:
  - Caching
  - Error handling
  - Retry logic
  - Data refresh (polling, user-triggered)

**What they don't do:**
- Direct UI rendering
- Business logic better suited for Domain layer
- Direct knowledge of other repositories

**Output:**
- Domain models (data classes tailored for app needs)
- Exposed as Streams (real-time) or Futures (one-time)

**Relationships:**
- Many-to-many with ViewModels
- Many-to-many with Services
- Should not be aware of each other

### Services
**What they do:**
- Wrap external data sources
- Expose async response objects (Future, Stream)
- Isolate data loading
- One service per data source

**What they don't do:**
- Hold state (stateless)
- Business logic
- Data transformation
- Caching

**Examples:**
- Platform APIs (iOS/Android native)
- REST/GraphQL API clients
- Local file access
- Database access
- Platform plugins (geolocation, camera, etc.)

**Relationships:**
- Many-to-many with Repositories
- Can be shared across the app

## Layer Communication Rules

1. **Lower layers stay independent**: Data doesn't depend on Domain or UI;
   Domain doesn't depend on UI.
2. **Unidirectional data flow**: Data -> ViewModel -> View.
3. **Events flow opposite**: View -> ViewModel -> Repository -> Service, or
   View -> ViewModel -> Use-case -> Repository -> Service when a Use-case is
   justified.
4. **No direct service calls from UI**: Views and ViewModels don't call
   Services directly.
5. **No forced Domain layer**: Skipping Use-cases is valid for simple logic.

## When to Use Which Layer

**Small CRUD apps:**
- UI Layer (Views + ViewModels)
- Data Layer (Repositories + Services)
- Skip Domain Layer

**Apps with complex business logic:**
- UI Layer
- Domain Layer (for complex, reusable logic)
- Data Layer
- ViewModels may use Repositories directly for simple operations, Use-cases for complex

**Enterprise apps with complex rules:**
- All three layers
- Consider enforcing Use-cases for all data access

## Testing Strategy

**UI Layer Tests:**
- Widget tests for Views
- Unit tests for ViewModels (mock Repositories)

**Domain Layer Tests:**
- Unit tests for Use-cases (mock Repositories)

**Data Layer Tests:**
- Unit tests for Repositories (mock Services)
- Integration tests for Services (actual APIs/databases)