Technology Stack

Flutter for cross-platform development
Dart as the primary programming language
bloc for state management
injectable for dependency injection
Dart Mappable for immutable data models
Dio for HTTP networking
isar for local database
Firebase for backend services

Clean Architecture

Domain Purity: The
```
domain
```
layer must be pure Dart. NO
```
package:flutter
```
imports.
Layer Dependency:
```
Presentation -> Domain <- Data
```
. Data layer implements Domain interfaces.
Feature-First 2.0: Enforce strict separation of
```
DataSources
```
(External/Raw) vs
```
Repositories
```
(Domain abstraction).

Directory Structure

Organize code according to feature-based Clean Architecture pattern (
```
featureA/bloc
```
,
```
featureA/models
```
,
```
featureA/views
```
)
Place cross-feature components in the
```
core
```
directory
Group shared widgets in
```
core/views/widgets
```
by type

Three-Layer Data Model Pattern

API Layer (ItemApiModel)
- Represents the raw data structure as received from the server
- Contains all fields provided by the API
- Should match the API contract exactly
Domain Layer (Item)
- Represents the internal data model
- Contains only the fields necessary for business logic
- Strips out unnecessary API fields
UI Layer (ItemUiState)
- Represents the data model optimized for UI rendering
- Contains parsed and formatted data ready for display
- Handles all UI-specific transformations

Data Model Rules

Use Dart Mappable for defining immutable UI states
Each layer should have its own type definition
The UI layer should use the UI state data models, never directly the domain model or the API model
The UI state model should be derived from the domain model, not the API model
The domain model should be derived from the API model, not the UI state model

Repository & DataSource Pattern

Repositories orchestrate between data sources (return Domain Model)
Data sources access raw data (return API Model)
The repository should be the source of truth, and it returns the domain model
DataSources MUST only contain raw SDK/API calls. No mapping or business logic.
No direct backend SDK/API calls outside DataSources

Data Flow

UI Event → BLoC (emit Loading) → Repository → DataSource (API/SDK)
    ↓
Response → Repository (map to Domain Entity) → BLoC (emit Success/Error) → UI

Dart 3 Language Features

Sealed Classes: Use
```
sealed class
```
for domain failures to enable exhaustive pattern matching across layers.
Records: Use records for lightweight multi-value returns where defining a full class is overkill (e.g.,
```
(String name, int age)
```
).
If-Case Pattern: Prefer
```
if (value case final v?)
```
over
```
if (value != null)
```
for null checking with binding.
Class Modifiers: Use
```
final
```
,
```
interface
```
,
```
base
```
, and
```
sealed
```
class modifiers to express API intent.

Error Handling

Functional Error Handling: Use
```
Either<Failure, T>
```
or
```
Result<T>
```
sealed classes. NEVER throw exceptions across layer boundaries.
Pattern Matching: Exhaustively handle all sealed class states using Dart 3.x
```
switch
```
expressions in UI and BLoCs.
Throw errors when needed, and catch them at appropriate boundaries
Log errors with context
Present user-friendly error messages in the UI
Avoid silent failures; always handle or propagate errors

Platform Channels & Native Integration

Use
```
MethodChannel
```
for one-off calls to native code (e.g., reading device info, triggering native APIs)
Use
```
EventChannel
```
for continuous streams from native to Flutter (e.g., sensor data, connectivity changes)
Place all channel code in a dedicated
```
platform/
```
directory within the relevant feature

Define channel names as constants:

static const channel = MethodChannel('com.app.feature/method')

Wrap all channel calls in a DataSource — never call
```
MethodChannel
```
directly from BLoC or UI
Handle
```
MissingPluginException
```
gracefully for platforms that don't implement the channel
Use
```
defaultTargetPlatform
```
checks to guard platform-specific behavior

FFI (Foreign Function Interface)

Use
```
dart:ffi
```
for performance-critical native C/C++ code
Define bindings in a separate class with clear documentation
Prefer Federated Plugins when sharing native code across multiple packages

Platform-Specific Code

Use
```
Platform.isAndroid
```
/
```
Platform.isIOS
```
for runtime checks (import
```
dart:io
```
)
For web, use
```
kIsWeb
```
from
```
package:flutter/foundation.dart
```
Prefer adaptive widgets (
```
Switch.adaptive
```
,
```
Slider.adaptive
```
) over manual platform checks where possible

architecture

NPX Install

Tags

SKILL.md Content

Technology Stack

Clean Architecture

Directory Structure

Three-Layer Data Model Pattern

Data Model Rules

Repository & DataSource Pattern

Data Flow

Dart 3 Language Features

Error Handling

Platform Channels & Native Integration

FFI (Foreign Function Interface)

Platform-Specific Code