Most Flutter MVPs start clean and end up messy. Not because the developer was careless, but because the first version is written in a hurry and nobody decides where things should live.
Then real users arrive. Feature requests start coming in, a second developer joins, and a "quick change" to the login screen breaks the profile page.
This post shows a small structure that keeps an MVP easy to change, without turning it into an over-engineered project. You do not need a big architecture to get most of the benefit.
The problem with the default layout
A common first layout looks like this:
lib/
screens/
widgets/
models/
services/
main.dart
It works for five screens. At thirty screens, widgets/ has 80 files, and nobody knows which widget belongs to which feature. To change "bookings", you open four different folders.
Group by feature, not by type
Put everything for one feature in one place:
lib/
core/
network/
theme/
utils/
features/
auth/
data/
domain/
presentation/
bookings/
data/
domain/
presentation/
profile/
data/
domain/
presentation/
main.dart
Each feature has three small layers:
data: talks to the API or database, and converts JSON to objects.
domain: plain Dart models and the rules of the feature.
presentation: screens, widgets and state.
core/ holds things shared across features, such as the HTTP client, theme and helpers. The rule is simple: a feature may use core/, but features should not reach into each other's folders.
For a tiny MVP you can skip domain/ and keep only data/ and presentation/. Add it when the logic grows.
Keep the API behind a repository
The most useful habit is to hide where data comes from. The screen should not know whether it is calling a REST API, Firebase or a local cache.
Start with a plain model:
dart
class Booking {
final String id;
final String doctorName;
final DateTime slot;
const Booking({
required this.id,
required this.doctorName,
required this.slot,
});
factory Booking.fromJson(Map json) {
return Booking(
id: json['id'] as String,
doctorName: json['doctor_name'] as String,
slot: DateTime.parse(json['slot'] as String),
);
}
}
Define what the feature needs, not how it gets it:
dart
abstract class BookingRepository {
Future> getBookings();
}
Then write the real implementation:
dart
import 'dart:convert';
import 'package:http/http.dart' as http;
class ApiBookingRepository implements BookingRepository {
ApiBookingRepository(this._client, this._baseUrl);
final http.Client _client;
final String _baseUrl;
@override
Future> getBookings() async {
final response = await _client.get(Uri.parse('$_baseUrl/bookings'));
if (response.statusCode != 200) {
throw Exception('Could not load bookings (${response.statusCode})');
}
final List<dynamic> data = jsonDecode(response.body) as List<dynamic>;
return data
.map((e) => Booking.fromJson(e as Map<String, dynamic>))
.toList();
}
}
The screen only knows about BookingRepository. Later, when you add caching or switch the backend, the screens do not change.
Why this pays off
You get three practical benefits.
Testing becomes easy. You can write a fake repository that returns fixed data and test the screen without a network:
dart
class FakeBookingRepository implements BookingRepository {
@override
Future> getBookings() async => [
Booking(
id: '1',
doctorName: 'Dr. Sharma',
slot: DateTime(2026, 1, 10, 10, 30),
),
];
}
Changes stay local. If the API renames doctor_name to doctorName, you edit one file in data/, not every screen.
New developers find things. Anyone asked to fix a bug in bookings opens features/bookings/ and sees everything in one place.
State management: keep it boring
Pick one approach and stay with it. Provider, Riverpod and Bloc all work well. The structure above does not depend on which one you choose. What matters is that the state object calls the repository, and the widget listens to the state. The widget should not call http directly.
Mistakes to avoid
Business logic inside widgets. Calculations, validation and API calls belong outside build().
Giant main.dart. Keep it for setup only: dependencies, theme and routes.
Features importing each other. If two features need the same thing, move it to core/.
Over-building on day one. Do not add layers you do not need yet. Start with data/ and presentation/, and add more when the code asks for it.
No error states. Every list screen needs a loading, empty and error view. Users meet the error state far more often than developers expect.
A quick checklist before you ship an MVP
Can a new developer find the code for any feature in under a minute?
Do screens talk to repositories rather than directly to the network?
Is there one place to change the base URL and the API keys?
Does every network call handle failure?
Can you test one feature without running the whole app?
If most answers are yes, version 2 will be far less painful.
Wrapping up
None of this is new, and none of it needs a heavy framework. It is just a habit: group code by feature, hide data sources behind a repository, and keep widgets for display. The cost at the start is a few extra files. The saving shows up the first time a requirement changes.
I work on app and web projects at Oprezo India in New Delhi, and these are the kind of things we try to settle before a project grows. If you structure your Flutter apps differently, I would like to hear what works for you in the comments.
Top comments (0)