Last updated: September 27, 2026

Bahasa Indonesia | English

Learning Objectives

After completing this codelab, students will be able to:

• explain SOLID principles and separation of concerns with Flutter code examples;
• distinguish feature-first vs layer-first structures and their trade-offs;
• explain the three layers (presentation, domain, data) and the dependency rule (dependencies point inward);
• distinguish entities vs models and the roles of repository, use case, and dependency injection;
• refactor the Week 5/6 project into a feature-first, layer-separated structure;
• test use cases with a fake repository, with no real database or network.

Prerequisites

• A laptop/PC and the portfolio repository (GitHub/GitLab) containing the Week 5 (week5_offline_notes) or Week 6 (campus_notify) project. This codelab refactors that project, it does not start from scratch.
• Flutter SDK, VS Code (Flutter/Dart extensions), an emulator or physical device.
• Week 3 knowledge (Riverpod, AsyncValue, GoRouter), Week 4 (repository pattern, Dio), and Weeks 5–6 (SQLite, secure storage).

1. SOLID in one Flutter example

Five principles, one sentence each plus the smell of violating them:

2. Three layers and the dependency rule

presentation (widgets, notifiers, router)
      |
      v  depends on
domain (entities, repository interfaces, use cases, failures)
      ^
      |  implemented by
data (models, repository impls, Dio, SQLite, secure storage)

The golden rule (dependency rule): dependencies only point inward. domain knows nothing about Flutter, Dio, or SQLite — so business logic can be purely unit-tested.

3. Feature-first vs layer-first

4. Role vocabulary

• Entity: a pure business object (no toMap/fromMap/toJson). Lives in domain.
• Model: an external data representation (JSON/SQLite) plus mapping to the entity. Lives in data.
• Repository interface: the contract the domain needs (e.g. fetchNotes()). Lives in domain.
• Repository impl: how the contract is fulfilled using Dio/SQLite. Lives in data.
• Use case: one business operation (e.g. GetNotes, SyncNotes). Lives in domain, called by presentation.
• DI: dependency injection via Riverpod providers (or get_it). Widgets never new a repository themselves.

1. Map files to layers

Open your Week 5 or 6 project and fill in this table in the README (example for campus_notify):

2. Flag three classic violations

Search your project with grep:

# Widgets touching network / database directly
rg "Dio\(|http\.|openDatabase|SharedPreferences\.getInstance|FlutterSecureStorage" lib/pages lib/widgets

# Business logic inside build()
rg "DateFormat|jsonDecode|\.toIso8601String" lib/pages lib/widgets

# Manual instantiation (leaking DI)
rg "Repository\(|Dio\(BaseOptions" lib/pages lib/providers

Each hit is one refactor item. Goal: all three searches return zero hits in the presentation folders after Lab 3.

3. Sketch the target structure

For one feature (notes or announcements):

lib/
├── core/
│   ├── failures.dart        # Domain failures (pure Dart)
│   └── providers.dart       # (optional) cross-feature providers
├── features/
│   └── notes/
│       ├── domain/
│       │   ├── entities/note.dart
│       │   ├── repositories/note_repository.dart  # interface!
│       │   └── usecases/get_notes.dart
│       │   └── usecases/add_note.dart
│       ├── data/
│       │   ├── models/note_model.dart
│       │   └── repositories/note_repository_impl.dart
│       └── presentation/
│           ├── providers/notes_providers.dart     # notifiers + DI
│           └── pages/notes_page.dart
└── routes.dart              # GoRouter + route constants

1. Pure entity (domain)

Create lib/features/notes/domain/entities/note.dart. No Flutter import, no mapping:

class Note {
  const Note({
    this.id,
    required this.title,
    this.body = '',
    required this.updatedAt,
    this.dirty = false,
  });

  final int? id;
  final String title;
  final String body;
  final DateTime updatedAt;
  final bool dirty;
}

2. Failures and the repository contract (domain)

Create lib/core/failures.dart and lib/features/notes/domain/repositories/note_repository.dart:

sealed class Failure {
  const Failure(this.message);
  final String message;
}

class LocalFailure extends Failure {
  const LocalFailure(super.message);
}

class NetworkFailure extends Failure {
  const NetworkFailure(super.message);
}

import '../../domain/entities/note.dart';
import '../../../../core/failures.dart';

abstract class NoteRepository {
  Future<({List<Note> notes, Failure? failure})> fetchNotes();
  Future<({Note? note, Failure? failure})> addNote({
    required String title,
    String body = '',
  });
}

This example uses Dart records to make success/failure explicit without exceptions leaking into presentation. Industry alternative: the fpdart/dartz packages (Either<Failure, T>) — the contract pattern is the same.

3. Model and implementation (data)

Create lib/features/notes/data/models/note_model.dart (mapping only here) and note_repository_impl.dart:

import '../../domain/entities/note.dart';

class NoteModel extends Note {
  const NoteModel({
    super.id,
    required super.title,
    super.body = '',
    required super.updatedAt,
    super.dirty = false,
  });

  Map<String, Object?> toMap() => {
        'id': id,
        'title': title,
        'body': body,
        'updated_at': updatedAt.toIso8601String(),
        'dirty': dirty ? 1 : 0,
      };

  factory NoteModel.fromMap(Map<String, Object?> map) {
    return NoteModel(
      id: (map['id'] as num?)?.toInt(),
      title: map['title'] as String? ?? '',
      body: map['body'] as String? ?? '',
      updatedAt: DateTime.tryParse(map['updated_at'] as String? ?? '') ??
          DateTime.fromMillisecondsSinceEpoch(0),
      dirty: ((map['dirty'] as num?)?.toInt() ?? 0) == 1,
    );
  }

  Note toEntity() => Note(
        id: id,
        title: title,
        body: body,
        updatedAt: updatedAt,
        dirty: dirty,
      );
}

import 'package:sqflite/sqflite.dart';
import '../../../../core/failures.dart';
import '../../domain/entities/note.dart';
import '../../domain/repositories/note_repository.dart';
import '../models/note_model.dart';

class NoteRepositoryImpl implements NoteRepository {
  NoteRepositoryImpl({required Future<Database> Function() openDb})
      : _openDb = openDb;

  final Future<Database> Function() _openDb;

  @override
  Future<({List<Note> notes, Failure? failure})> fetchNotes() async {
    try {
      final db = await _openDb();
      final rows =
          await db.query('notes', orderBy: 'updated_at DESC');
      final notes =
          rows.map((r) => NoteModel.fromMap(r).toEntity()).toList();
      return (notes: notes, failure: null);
    } catch (e) {
      return (
        notes: const <Note>[],
        failure: LocalFailure('Failed to read notes: $e'),
      );
    }
  }

  @override
  Future<({Note? note, Failure? failure})> addNote({
    required String title,
    String body = '',
  }) async {
    try {
      final db = await _openDb();
      final now = DateTime.now();
      final id = await db.insert(
        'notes',
        NoteModel(
            title: title, body: body, updatedAt: now, dirty: true)
            .toMap(),
      );
      return (
        note: Note(id: id, title: title, body: body,
            updatedAt: now, dirty: true),
        failure: null,
      );
    } catch (e) {
      return (note: null,
          failure: LocalFailure('Failed to save note: $e'));
    }
  }
}

4. Use case: one business operation

Create lib/features/notes/domain/usecases/get_notes.dart:

import '../../../../core/failures.dart';
import '../entities/note.dart';
import '../repositories/note_repository.dart';

class GetNotes {
  const GetNotes(this._repository);
  final NoteRepository _repository;

  Future<({List<Note> notes, Failure? failure})> call() {
    return _repository.fetchNotes();
  }
}

1. Dependency injection with Riverpod

Create lib/features/notes/presentation/providers/notes_providers.dart. This is the single wiring point:

import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../../data/repositories/note_repository_impl.dart';
import '../../domain/repositories/note_repository.dart';
import '../../domain/usecases/get_notes.dart';
import '../../domain/entities/note.dart';

// Data layer: the database opener is injected (easy to fake in tests)
final noteRepositoryProvider = Provider<NoteRepository>((ref) {
  return NoteRepositoryImpl(openDb: openNotesDb);
});

// Domain layer: the use case receives an abstraction, not an impl
final getNotesProvider = Provider<GetNotes>((ref) {
  return GetNotes(ref.watch(noteRepositoryProvider));
});

// Presentation layer: state for the UI
final notesProvider = FutureProvider<List<Note>>((ref) async {
  final result = await ref.watch(getNotesProvider).call();
  if (result.failure != null) throw Exception(result.failure!.message);
  return result.notes;
});

2. Pages only read state

The clean notes_page.dart contains no SQL, Dio, JSON, or raw date formatting:

class NotesPage extends ConsumerWidget {
  const NotesPage({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(notesProvider);
    return state.when(
      loading: () =>
          const Center(child: CircularProgressIndicator()),
      error: (e, _) => ErrorView(
        message: '$e',
        onRetry: () => ref.invalidate(notesProvider),
      ),
      data: (notes) => notes.isEmpty
          ? const Center(child: Text('No notes yet.'))
          : NotesList(notes),
    );
  }
}

3. Verify the dependency rule

Run these three checks; all must pass:

# 1. Presentation free of raw data (must return ZERO hits)
rg "Dio\(|openDatabase|getDatabasesPath|FlutterSecureStorage|SharedPreferences\.getInstance|jsonDecode" lib/features/*/presentation lib/pages

# 2. Domain free of frameworks & packages (must return ZERO hits)
rg "import 'package:flutter|import 'package:dio|import 'package:sqflite|import 'package:firebase" lib/features/*/domain lib/core

# 3. Static analysis + tests
flutter analyze
flutter test

The role of AI in this codelab

AI may propose a folder reorganization, but you assess the trade-offs. Wrong architecture (over-engineering simple CRUD, or under-engineering complex features) costs more than ugly code.

AI Prompt Challenge

Ask your AI coding assistant with this prompt:

My Flutter project: campus_notify (auth + FCM + announcement list).
Current state: lib/{data, providers, pages, messaging} folders,
repositories mixed with implementations, widgets calling Dio directly.
Tasks:
1. Propose a feature-first Clean Architecture structure
   (presentation/domain/data) for the auth + announcements features.
2. For each old file, state its new destination (move/split/delete).
3. Flag what would be over-engineering if applied to simple CRUD,
   and when a use case is truly needed vs repository straight to notifier.
4. Show the Riverpod DI wiring (no extra DI package).
Explain the trade-off of every decision.

AI Verification Checklist

Before accepting the AI proposal, verify and record your findings in the README/docs:

• Does the repository interface live in domain and the implementation in data? (reject it if the AI puts both in one folder).
• Is domain free of Flutter/Dio/SQLite/Firebase imports? Check with grep, not by skimming.
• Did the AI create a use case for every one-line CRUD? (that is over-engineering: repository straight to notifier suffices, with a written reason).
• Is the entity mapping-free (toMap/fromMap/toJson only in the model)?
• Is DI wiring centralized in providers, with widgets never calling new Repository() themselves?
• Your final decision and technical rationale; you may disagree with the AI as long as you argue your case.

Refactoring Challenge

1. Apply the same pattern to a second feature (auth or announcements): entity + repository interface + impl + 1 use case + provider wiring. Do not leave one feature clean and the rest dirty.
2. Extract date formatting and route parsing into pure functions in lib/core/format.dart so they can be tested without widgets.
3. Convert all raw exceptions into user-friendly Failure objects before they reach the UI; the UI only ever receives a message.

Testing: use cases with a fake repository

Create test/get_notes_test.dart. The domain is tested purely — no SQLite, no Dio, no Firebase:

import 'package:flutter_test/flutter_test.dart';

class FakeNoteRepository implements NoteRepository {
  FakeNoteRepository({this.items = const [], this.fail = false});

  final List<Note> items;
  final bool fail;

  @override
  Future<({List<Note> notes, Failure? failure})> fetchNotes() async {
    if (fail) {
      return (
        notes: const <Note>[],
        failure: const LocalFailure('db locked (simulated)'),
      );
    }
    return (notes: items, failure: null);
  }

  @override
  Future<({Note? note, Failure? failure})> addNote({
    required String title,
    String body = '',
  }) {
    throw UnimplementedError();
  }
}

void main() {
  test('GetNotes forwards the repository list', () async {
    final repo = FakeNoteRepository(items: [
      Note(title: 'A', updatedAt: DateTime(2026, 9, 27)),
    ]);
    final result = await GetNotes(repo).call();
    expect(result.failure, isNull);
    expect(result.notes.length, 1);
    expect(result.notes.first.title, 'A');
  });

  test('GetNotes forwards failure without throwing', () async {
    final repo = FakeNoteRepository(fail: true);
    final result = await GetNotes(repo).call();
    expect(result.failure, isA<LocalFailure>());
    expect(result.notes, isEmpty);
  });
}

Run:

flutter analyze
flutter test

Common errors and fixes

Self-verification checklist

• The three sterility greps (presentation & domain) return zero hits.
• Interfaces in domain, implementations in data, mapping only in models.
• Widgets never instantiate repositories; everything goes through providers.
• The app behaves identically before/after refactoring (screenshot evidence).
• flutter analyze is clean and all tests pass.

Mini project / Industry Challenge

Refactor your Week 5 or 6 project into feature-first Clean Architecture (continue the same repository, not a new project):

1. At least 1 complete feature (notes or announcements) split into domain/ (entity, repository interface, use case, failure) + data/ (model, repository impl) + presentation/ (provider wiring, pages).
2. Dependency rule proven: include the three sterility grep results in the README.
3. Identical behavior: before/after screenshots per feature under screenshots/.
4. At least 2 passing tests (success + failure use case with a fake repository).
5. Complete the AI Challenge and document the prompt, the proposal-vs-final-decision table, and the technical rationale in docs/.
6. Push to the portfolio repository under 07-week-7-clean-architecture/ (or continue the source week's folder + note the refactor in the README) with lib/, test/, docs/, README.md, and screenshots/. The README explains the objective, the layer diagram + dependency direction, main features, tech stack, how to run, and the result achieved.

Reflection

• Why must the repository interface live in domain, not in data? What breaks if it is reversed?
• When is a use case truly needed, and when is repository straight to notifier enough?
• What does over-engineering (a use case per one-line CRUD) cost a small team? When is the cost worth it?
• Which part of the AI proposal did you reject or simplify, and why?

Supporting references

• Week 7 Slides: Clean Architecture
• Flutter: App architecture guide
• The Clean Architecture (Robert C. Martin)
• Riverpod: Providers & dependency injection
• Dart: Records (paired success/failure returns)
• fpdart package (Either alternative)
• GoRouter: redirect & deep linking
• Learn Dart in Y Minutes