App Architecture That Survives Growth

lib/
  main.dart
  app/
    app.dart                 # MaterialApp, theme, router
    di.dart                  # dependency wiring
  core/
    error/failures.dart
    network/api_client.dart
    utils/result.dart
  features/
    lessons/
      domain/
        lesson.dart          # entity — pure Dart
        lesson_repository.dart  # abstract interface
        get_lessons.dart     # use case
      data/
        lesson_dto.dart      # wire format + mapping
        lesson_api.dart
        lesson_local_store.dart
        lesson_repository_impl.dart
      presentation/
        lessons_controller.dart
        lessons_screen.dart
        widgets/lesson_tile.dart
    profile/
      domain/ data/ presentation/

// Pure Dart. No Flutter, no JSON, no database.
class Lesson {
  const Lesson({
    required this.id,
    required this.title,
    required this.level,
    required this.minutes,
  });

  final String id;
  final String title;
  final Level level;
  final int minutes;

  // Business rules live with the entity that owns them
  bool get isQuickRead => minutes <= 10;

  @override
  bool operator ==(Object other) =>
      other is Lesson && other.id == id;

  @override
  int get hashCode => id.hashCode;
}

// The interface lives in domain; the implementation lives in data.
// Domain defines what it needs; data figures out how.
abstract interface class LessonRepository {
  Future<List<Lesson>> getLessons({Level? level});
  Future<Lesson?> getLesson(String id);
  Stream<List<Lesson>> watchBookmarked();
}

sealed class Result<T> {
  const Result();
}

final class Ok<T> extends Result<T> {
  const Ok(this.value);
  final T value;
}

final class Err<T> extends Result<T> {
  const Err(this.failure);
  final Failure failure;
}

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

final class NetworkFailure extends Failure {
  const NetworkFailure() : super('No internet connection');
}

final class ServerFailure extends Failure {
  const ServerFailure(super.message, {this.statusCode});
  final int? statusCode;
}

final class CacheFailure extends Failure {
  const CacheFailure() : super('Could not read local data');
}

// In the controller — exhaustive, compiler-checked handling
final result = await getLessons(level: Level.beginner);

state = switch (result) {
  Ok(value: final lessons) => LessonsState.loaded(lessons),
  Err(failure: NetworkFailure()) => const LessonsState.offline(),
  Err(failure: final f) => LessonsState.error(f.message),
};

// Mirrors the wire format exactly, including its warts
class LessonDto {
  const LessonDto({
    required this.id,
    required this.title,
    required this.levelName,
    required this.readingTimeSeconds,
  });

  final String id;
  final String title;
  final String levelName;
  final int readingTimeSeconds;

  factory LessonDto.fromJson(Map<String, dynamic> json) => LessonDto(
        id: json['lesson_id'] as String,
        title: json['title'] as String,
        levelName: json['difficulty'] as String,
        readingTimeSeconds: json['reading_time_s'] as int? ?? 0,
      );

  // Mapping to the domain shape happens here, once
  Lesson toDomain() => Lesson(
        id: id,
        title: title,
        level: Level.values.byName(levelName.toLowerCase()),
        minutes: (readingTimeSeconds / 60).ceil(),
      );
}

// With Riverpod, wiring is just providers — overridable in tests
final apiClientProvider = Provider<ApiClient>((ref) {
  final client = ApiClient(baseUrl: const String.fromEnvironment('API_URL'));
  ref.onDispose(client.close);
  return client;
});

final lessonRepositoryProvider = Provider<LessonRepository>((ref) {
  return LessonRepositoryImpl(
    api: LessonApi(ref.watch(apiClientProvider)),
    local: ref.watch(lessonLocalStoreProvider),
  );
});

// In a widget test, swap the real repository for a fake:
ProviderScope(
  overrides: [
    lessonRepositoryProvider.overrideWithValue(FakeLessonRepository()),
  ],
  child: const MyApp(),
);