flutter-clean-arch

You are working with Clean Architecture in a Flutter project.

Layer Responsibilities

┌─────────────────────────────────────────┐
│  PRESENTATION                           │
│  Modules, Screens, Controllers (Cubits) │
│  Only knows: Domain entities + Usecases │
├─────────────────────────────────────────┤
│  DOMAIN (pure Dart, no Flutter)         │
│  Entities, Repository interfaces,       │
│  Usecases                               │
│  Depends on: nothing                    │
├─────────────────────────────────────────┤
│  DATA                                   │
│  Models, Datasources, Repo impls        │
│  Depends on: Domain interfaces + Dio    │
└─────────────────────────────────────────┘

Full Feature Scaffold

When argument is scaffold or no argument, create all layers for <feature_name>:

Domain Layer

entity (domain/entities/<feature>.dart):

import 'package:equatable/equatable.dart';

class <Feature> extends Equatable {
  final String id;
  final String name;
  // Add all business-relevant fields (no JSON, no framework types)

  const <Feature>({
    required this.id,
    required this.name,
  });

  @override
  List<Object?> get props => [id, name];

  <Feature> copyWith({String? id, String? name}) => <Feature>(
    id: id ?? this.id,
    name: name ?? this.name,
  );
}

repository interface (domain/repositories/<feature>_repository.dart):

import '../entities/<feature>.dart';

abstract class <Feature>Repository {
  Future<List<<Feature>>> getAll();
  Future<<Feature>> getById(String id);
  Future<void> create(<Feature> entity);
  Future<void> update(<Feature> entity);
  Future<void> delete(String id);
}

usecases (domain/usecases/<feature>/):

Each usecase = one file, one responsibility:

// get_<feature>s_usecase.dart
class Get<Feature>sUsecase {
  final <Feature>Repository _repository;
  Get<Feature>sUsecase(this._repository);

  Future<List<<Feature>>> call() => _repository.getAll();
}

// create_<feature>_usecase.dart
class Create<Feature>Usecase {
  final <Feature>Repository _repository;
  Create<Feature>Usecase(this._repository);

  Future<void> call(<Feature> entity) => _repository.create(entity);
}

Data Layer

model (data/models/<feature>_model.dart):

import '../../domain/entities/<feature>.dart';

class <Feature>Model {
  final String id;
  final String name;

  const <Feature>Model({required this.id, required this.name});

  factory <Feature>Model.fromJson(Map<String, dynamic> json) =>
      <Feature>Model(
        id:   json['id']   as String,
        name: json['name'] as String,
      );

  Map<String, dynamic> toJson() => {'id': id, 'name': name};

  <Feature> toEntity() => <Feature>(id: id, name: name);

  static <Feature>Model fromEntity(<Feature> entity) =>
      <Feature>Model(id: entity.id, name: entity.name);
}

datasource (data/datasources/<feature>_datasource.dart):

import 'package:dio/dio.dart';
import '../models/<feature>_model.dart';

class <Feature>Datasource {
  final Dio _dio;
  <Feature>Datasource(this._dio);

  Future<List<<Feature>Model>> getAll() async {
    final response = await _dio.get('/<feature>s');
    return (response.data as List)
        .map((e) => <Feature>Model.fromJson(e as Map<String, dynamic>))
        .toList();
  }

  Future<<Feature>Model> getById(String id) async {
    final response = await _dio.get('/<feature>s/$id');
    return <Feature>Model.fromJson(response.data as Map<String, dynamic>);
  }

  Future<void> create(<Feature>Model model) async {
    await _dio.post('/<feature>s', data: model.toJson());
  }

  Future<void> update(<Feature>Model model) async {
    await _dio.put('/<feature>s/${model.id}', data: model.toJson());
  }

  Future<void> delete(String id) async {
    await _dio.delete('/<feature>s/$id');
  }
}

repository impl (data/repositories/<feature>_repository_impl.dart):

import '../../domain/entities/<feature>.dart';
import '../../domain/repositories/<feature>_repository.dart';
import '../datasources/<feature>_datasource.dart';
import '../models/<feature>_model.dart';

class <Feature>RepositoryImpl implements <Feature>Repository {
  final <Feature>Datasource _dataSource;
  <Feature>RepositoryImpl(this._dataSource);

  @override
  Future<List<<Feature>>> getAll() async {
    final models = await _dataSource.getAll();
    return models.map((m) => m.toEntity()).toList();
  }

  @override
  Future<<Feature>> getById(String id) async {
    final model = await _dataSource.getById(id);
    return model.toEntity();
  }

  @override
  Future<void> create(<Feature> entity) =>
      _dataSource.create(<Feature>Model.fromEntity(entity));

  @override
  Future<void> update(<Feature> entity) =>
      _dataSource.update(<Feature>Model.fromEntity(entity));

  @override
  Future<void> delete(String id) => _dataSource.delete(id);
}

When argument is audit

Read the existing code for <feature_name> and check:

1. Domain isolation: Do entities import anything from Flutter/Dio/external? (They shouldn't)
2. Repository pattern: Does the datasource return models? Does the repo impl map to entities?
3. Usecase single responsibility: Does each usecase do exactly one thing?
4. Dependency direction: Does data layer depend on domain? (Yes, correct) Does domain depend on data? (No, wrong)
5. Model ↔ Entity separation: Are API models separate from domain entities?
6. Exception handling: Are data-layer exceptions caught and re-thrown as domain exceptions?

Report findings and fix any violations.

Architecture Rules

1. Domain layer has zero external dependencies — pure Dart, no Flutter, no Dio
2. Entities use Equatable — value equality for BLoC state comparisons
3. Models handle JSON — entities never have fromJson/toJson
4. Repository interface in domain — implementation in data
5. Usecases are thin — orchestrate repo calls, no business logic in datasources
6. One usecase = one operation — don't create MenuUsecases with 5 methods
7. Datasources return models — repositories return entities
8. Exceptions: datasource throws HTTP exceptions, repository catches and rethrows domain exceptions

Instructions

1. Read existing domain/data files before creating new ones
2. Check core/lib/injections.dart to see what's already registered
3. Only create layers that don't exist yet
4. After scaffolding, run /flutter-di to register new dependencies
5. After DI, run /flutter-state to create the Cubit