Coder Legion - Recent posts tagged dart

flutter_skin Alpha — Material 3 Tokens, Live Preview & Typography | Remote Skin

Wed, 12 Aug 2026 08:36:49 +0000

Alpha V1 is live.

→ Full Material 3 color token support
→ Live skin preview directly in the dashboard
→ Typography tokens — change your app's font remotely

No rebuild. No App Store update. Publish from the
dashboard, app updates live.

─────────────────────────────

🔗 Links

📦 Package: pub.dev/packages/flutter_skin
🖥️ Dashboard: app.fskin.dev
📖 Docs: docs.fskin.dev

─────────────────────────────

What's coming in Beta:
→ Spacing tokens
→ Border radius tokens

→ A/B testing
→ MCP server for AI-generated skins

flutter_skin — Live Remote Skin Engine Demo | Change Flutter Colors Without Rebu

Mon, 06 Jul 2026 06:20:40 +0000

Live Remote Skin Engine Demo | Change Flutter Colors Without Rebuilding.
This is the first demo of flutter_skin — a remote skin engine
for Flutter I've been building for the past few months.

This is the alpha. Color tokens only for now. Typography,
spacing, border radii, and A/B testing are coming.

Built by Badr Kouki
Flutter contributor | pub.dev publisher

Reflection in Dart

Mon, 29 Jun 2026 09:39:48 +0000

I have just published an article on using dart:mirrors for reflection and dynamic invocation in Dart. Many languages support reflection, and Dart is among them. The article introduces the package—which provides reflection support in Dart—examines its limitations, and presents both experimental and practical examples.

Checkout

Stop Guessing Frame Drops: Passive Zero Overhead Performance Telemetry for Flutter

Fri, 05 Jun 2026 04:07:58 +0000

Automatically capture frame drops (jank) and isolate rendering bottlenecks on the UI and Raster threads directly in your dev console

Every Flutter developer knows the pain of subtle micro-stuttering

A slight visual hiccup when navigating routes.
Scroll stutters on content-heavy feed lists.
Sluggish transitions when pulling up custom sheets.

We call this jank when the Flutter rendering pipeline fails to finish producing a frame within the device's hardware refresh budget (typically 16.67ms for 60Hz or 8.33ms for high refresh 120Hz screens). But actively hunting down these frame drops is tedious. You're forced to keep a browser tab open with Flutter DevTools, maintain active Socket connections, or install heavy analytics SDKs that bloat your production bundle.

That's why I built jank_scout. It passively monitors rendering lifecycle timings, analyzes thread bottlenecks, and outputs clean diagnostics directly to your terminal. Best of all, it completely tree-shakes itself out of your production release.

What It Looks Like in Practice

When a rendering timing budget is broken, jank_scout automatically identifies whether the freeze occurred on the UI Thread (CPU) or the Raster Thread (GPU) and displays a diagnostic ASCII report in your console

+----------------------------------------------------------------------+
| TELEMETRY REPORT:  [PIPELINE CRITICAL INTERRUPT]
+----------------------------------------------------------------------+
| Target Route: /details
| Budget: 16.67 ms (Target FPS: 60)
| Frame Render Time: 76.50 ms (Overrun: 358.9%, +59.83 ms)
| Thread Breakdowns:
|   - UI Thread (CPU Build):  68.20 ms
|   - Raster Thread (GPU):   8.30 ms
+----------------------------------------------------------------------+
| Bottleneck Analysis:
| BOTTLENECK: UI Thread (CPU Boundary). Diagnostic: Excessive execution cycle detected on the Dart isolate runtime loop. Remediate by auditing synchronous serialization, unoptimized layout passes, or high-frequency state emissions violating state boundary conditions.
+----------------------------------------------------------------------+

The Architecture Under the Hood
How does it hook into the engine with zero dependencies?

It utilizes Flutter's native SchedulerBinding callback pipeline to receive raw frame timelines asynchronously

SchedulerBinding.instance.addTimingsCallback((List<FrameTiming> timings) {
  // Pass timing metrics into the monitor engine
  JankScout.processTimings(timings);
});

jank_scout breaks down each frame into

UI Thread Time: widget tree creation, layout cycles, and drawing calls.
Raster Thread Time: GPU execution translating the layer tree into pixels.

Safe Production Tree-Shaking

To ensure that the package adds exactly zero bytes and zero background overhead in your production app, jank_scout wraps its entire registration and logging cycles inside assert boundaries and compiler optimizations

assert(() {
  // This code is completely stripped out during `flutter build --release`
  _initializeFrameMonitor();
  return true;
}());

Real-World Case Study: The Synchronous JSON List Freeze
Let's look at a classic local performance bottleneck parsing a massive JSON payload inside your UI widget builds.

X The Bad Code (Stalls UI Thread)

class FeedListScreen extends StatelessWidget {
  final String rawJsonString; // Large JSON string from network or local cache

  const FeedListScreen({super.key, required this.rawJsonString});

  @override
  Widget build(BuildContext context) {
    // ❌ CRITICAL JANK: Blocks Dart's main single-threaded event loop
    final List<dynamic> decodedData = jsonDecode(rawJsonString);
    final List<FeedItem> items = decodedData.map((e) => FeedItem.fromJson(e)).toList();

    return ListView.builder(
      itemCount: items.length,
      itemBuilder: (context, index) => FeedItemCard(item: items[index]),
    );
  }
}

Since Dart is single-threaded, running jsonDecode synchronously forces the UI thread to freeze while processing. The user experiences a frame drop. jank_scout immediately catches this and flags the UI Thread (CPU Boundary) as the culprit.

The Clean Fix (Background Concurrency)
To restore a butter-smooth 60 or 120 FPS scrolling list, offload the processing to a background thread using Dart isolates.

Option A: Spawning a Temporary Isolate using compute()

Future<List<FeedItem>> loadFeedAsync(String rawJson) async {
  // Offloads JSON processing to a temporary worker isolate
  return await compute(_parseJsonFeed, rawJson);
}

// Global or top-level function
List<FeedItem> _parseJsonFeed(String rawJson) {
  final List<dynamic> decoded = jsonDecode(rawJson);
  return decoded.map((e) => FeedItem.fromJson(e)).toList();
}

Option B:Persistent Isolate using Isolate.spawn()
For continuous large payloads, keep a dedicated worker isolate alive to save isolate initialization latency

Future<List<FeedItem>> parseWithManualIsolate(String rawJson) async {
  final receivePort = ReceivePort();
  
  final isolate = await Isolate.spawn(
    _isolateWorkerEntryPoint,
    _IsolatePayload(rawJson, receivePort.sendPort),
  );

  final List<FeedItem> items = await receivePort.first as List<FeedItem>;

  isolate.kill(priority: Isolate.beforeNextEvent);
  receivePort.close();

  return items;
}

By moving CPU intensive operations off the main isolate, scrolling stays fluid, the event loop remains clear, and jank_scout console output remains silent confirming optimal performance

Get Started in 3 Steps
1. Add dependency
Add the dependency to your pubspec.yaml

dependencies:
  jank_scout: ^0.0.3

2. Initialize in main.dart

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Set your target device FPS
  JankScout.initialize(targetFps: 60.0);
  
  runApp(const MyApp());
}

3. Add Router Route Tracking
Add the navigation observer in your MaterialApp to associate performance degradation reports with specific screens

MaterialApp(
  navigatorObservers: [JankScoutObserver()],
  initialRoute: '/',
  routes: {
    '/': (context) => const HomeScreen(),
    '/feed': (context) => const FeedListScreen(),
  },
);

Try It Out!
Let's make local Flutter development smoother together!

pub.dev: junk_scout
GitHub: Github Url
Website: My Portfolio

If you find jank_scout helpful, drop a ⭐ on GitHub and a like on pub.dev! Have any questions or feature ideas? Let's discuss in the comments below!

The Quiet Work Behind a Flutter Endpoint

Wed, 13 May 2026 21:22:11 +0000

In a real app, an endpoint is rarely just an endpoint. It is a tiny agreement between the backend, the network client, the request model, the repository, the use case, the UI state, and sometimes one very tired developer trying to remember whether this response returns JSON, bytes, a list, or a 200 with vibes.

This is the part of my codebase I keep coming back to: the path from repository to service locator. It is not the flashiest part of the app, but it decides whether new features feel smooth or whether every new API integration becomes a small argument with myself.

The shape I keep repeating

The project I worked on today has a fairly familiar Flutter structure:

feature folders
data sources for remote calls
repositories for parsing and decision-making
domain use cases
a shared DioClient
GetIt as the service locator

The pattern is not exotic, but it has saved me more times than I expected.

When I add a new endpoint, I usually move through the same mental chain:

Add the URL constant.
Add the method to the API service contract.
Implement the Dio call.
Expose it through the repository contract.
Parse the response in the repository implementation.
Wrap it in a use case.
Register the use case, repository, and API service in sl.
Finally, call it from the UI or bloc/cubit layer.

That sounds like a lot when written out. In practice, it gives each layer one job. The API service talks HTTP. The repository turns raw responses into app-friendly objects. The use case gives the UI a clean entry point. The service locator makes the whole thing reachable without manually wiring constructors everywhere.

It is boring in a good way. And in mobile apps, "boring in a good way" is a compliment.

Where things got slightly less boring

The endpoints I worked around were not all the same shape.

Some were plain JSON requests:

final response = await sl<DioClient>().post(
  ApiUrls.createBooking,
  data: requestBody.toJson(),
  options: Options(
    headers: {'Authorization': 'Bearer $token'},
  ),
);

Some needed query parameters:

final response = await sl<DioClient>().get(
  ApiUrls.getBookings,
  queryParameters: {
    'page': page,
    if (startDate?.trim().isNotEmpty == true) 'startDate': startDate,
    if (endDate?.trim().isNotEmpty == true) 'endDate': endDate,
  },
  options: Options(
    headers: {'Authorization': 'Bearer $token'},
  ),
);

Some involved multipart uploads, which always make the room a little warmer:

final formData = FormData();

for (final entry in requestBody.toFormFields().entries) {
  formData.fields.add(MapEntry(entry.key, entry.value));
}

if (imagePath != null && imagePath.trim().isNotEmpty) {
  formData.files.add(
    MapEntry(
      'image',
      await MultipartFile.fromFile(
        imagePath,
        filename: imagePath.split(RegExp(r'[\\/]')).last,
      ),
    ),
  );
}

And then there were the document/image endpoints, where the response is not a neat JSON object at all. For those, the Dio options matter:

final response = await sl<DioClient>().get(
  ApiUrls.downloadDocument(documentId),
  options: Options(
    headers: {
      'Authorization': 'Bearer $token',
      'Accept': '*/*',
    },
    responseType: ResponseType.bytes,
  ),
);

That small ResponseType.bytes line is the kind of thing you forget once, then remember forever.

Why I do not let the UI talk directly to Dio

There was a time when I would have been tempted to call Dio directly inside a screen, especially if the endpoint looked small.

Today-me does not trust that version of me.

The screen should not care if the endpoint is GET, POST, multipart, or returning bytes. It should not know whether the backend sends a list directly or wraps it inside a data key. It should not know that one endpoint needs timezone as a query parameter while another one needs a generated ID in the URL.

So the API service stays close to HTTP:

abstract class VendorApiService {
  Future<Either> getTransactions({int page = 1});
}

Then the repository handles the translation:

class VendorRepositoryImpl extends VendorRepository {
  @override
  Future<Either> getTransactions({int page = 1}) async {
    final result = await sl<VendorApiService>().getTransactions(page: page);

    return result.fold(
      (error) => Left(error),
      (data) async {
        try {
          final response = data as Response;
          final transactions = TransactionsResponse.fromJson(
            (response.data as Map?)?.cast<String, dynamic>() ??
                const <String, dynamic>{},
          );
          return Right(transactions);
        } catch (e) {
          return Left('Failed to parse transactions.');
        }
      },
    );
  }
}

That separation pays off when something changes. If the backend adjusts a response shape, I usually fix the repository. If auth headers are wrong, I look at the API service or client. If the UI state is confused, I inspect the use case call and state handling.

It gives the bug a neighborhood.

The service locator is where I check my work

GetIt is not just a dependency bucket for me. It is also the final checklist.

When I register a new endpoint flow, I have to ask:

Did I register the API service?
Did I bind the repository interface to its implementation?
Did I add the new use case?
Am I using the same feature boundary as the rest of the app?

The registrations usually look simple:

final sl = GetIt.instance;

void setupServiceLocator() {
  sl.registerLazySingleton<VendorApiService>(
    () => VendorApiServiceImpl(),
  );

  sl.registerLazySingleton<VendorRepository>(
    () => VendorRepositoryImpl(),
  );

  sl.registerLazySingleton<GetVendorTransactionsUseCase>(
    () => GetVendorTransactionsUseCase(),
  );
}

But that simplicity is exactly why I like it. When a use case fails at runtime because it was never registered, the error is loud and direct. Annoying, yes, but honest.

The more dangerous bugs are the quiet ones: a method exists in the API service but not the repository, a repository parses the wrong model, or a use case accepts the wrong params and the UI starts passing half-correct data.

That is why I try to move through the chain in order. URL. Service. Repository. Use case. Service locator. UI. If I jump around too much, I eventually pay for it.

One small detail that mattered more than expected

A pattern I appreciated today was keeping request bodies responsible for serialization.

The endpoint method should not be manually assembling random maps everywhere if the request already has a model. This:

data: requestBody.toJson(),

is much easier to trust than scattering field names across multiple screens.

For multipart requests, I still have to be more hands-on because files and repeated fields need special handling. But even there, I prefer pushing normal text fields through something like toFormFields() and letting the service only deal with the multipart-specific parts.

It keeps the code from slowly becoming a collection of tiny string mistakes.

And yes, a single wrong field name can waste thirty minutes. Sometimes more. I am not proud, I am just reporting from the field.

The endpoint constants are not just strings

The app keeps endpoint paths centralized behind an ApiUrls style class. The real values come from environment configuration, but the usage stays clean:

class ApiUrls {
  static String get baseUrl => 'https://api.example.com/';

  static final createBooking = '${baseUrl}client/create-booking';

  static String bookingReceipt(String bookingId) {
    return '${baseUrl}payment/$bookingId/booking';
  }
}

I like this because dynamic endpoints become explicit functions instead of random interpolation inside service methods.

The tradeoff is that the constants file can grow large if I am not careful. Once an app has auth, client flows, vendor flows, analytics, notifications, payments, documents, chat, and logging, the endpoint list starts looking like a city map.

Still, I prefer one crowded map to endpoint strings hiding in twenty different files.

What I noticed while wiring everything

The endpoint layer quietly reveals the personality of the app.

In this project, some features are simple CRUD. Others are more workflow-heavy: bookings, contracts, payouts, profile updates, analytics, reviews, notifications, documents, and media. That means the network layer cannot assume every response is the same kind of JSON.

A few decisions made the code easier to reason about:

keeping auth token reads inside the API service layer
returning Either so failures stay explicit
parsing inside repositories instead of UI code
using use cases as the UI-facing API
making file downloads return bytes instead of pretending they are normal models
registering dependencies in one place so missing pieces are easier to spot

I also liked the small caching choice around relatively stable data. Not every endpoint deserves a network call every time. For data that rarely changes, a short-lived cache can remove friction without turning the app into a stale-data museum.

That is the kind of decision that is easy to skip when you are just trying to "make the endpoint work." But those little choices are where the app starts to feel more mature.

The part I keep learning

Writing endpoints is not hard because of the syntax.

It is hard because each endpoint carries assumptions:

Does it need auth?
Is the body JSON or multipart?
Does it return a map, list, file, or empty success?
Are IDs in the path or query params?
Should the repository parse it or pass through the raw response?
Does the UI need a typed model, bytes, or just success/failure?
Should this use case take a params object instead of three loose strings?

None of these questions are dramatic. But they are the difference between a codebase that stays calm and one that becomes stressful to touch.

By the end of the day, the win was not only that endpoints were wired. The real win was that the flow still made sense after more endpoints were added.

That matters.

Because tomorrow another endpoint will arrive with one weird query parameter, one optional file, one backend response that does not look like the others, and one screen waiting for a clean result.

And when it does, I would rather follow a familiar path than negotiate with chaos again.

The Day White Became a Bug

Wed, 13 May 2026 20:46:52 +0000

Today started with one of those tasks that looks almost too small to deserve a branch: prepare the Flutter app for dark mode by making sure colors are centralized.

Simple enough, right?

Find the hardcoded colors. Move them into AppColors class. Replace the literals. Run analyzer. Go eat something.

Flutter, naturally, had a few notes.

The first scan told the real story. There were direct Colors.white calls, direct Colors.black, Colors.grey[600], Colors.transparent, and a handful of Color(0x...) values hiding in screens, cards, bottom sheets, painters, buttons, notification badges, and little UI edges that probably nobody thinks about until dark mode makes them painfully visible.

And that is the thing about dark mode: it punishes casual color decisions.

A hardcoded Colors.white is harmless in a light theme. It feels obvious. Of course the card background is white. Of course the modal is white. Of course the icon on the primary button is white.

Until the app theme changes and that same “obvious” value becomes the one thing refusing to adapt.

The suspicious innocence of Colors.white

The cleanup made me notice how often Flutter code uses color constants as if they are design decisions instead of implementation details.

This kind of code is easy to write:

Container(
color: Colors.white,
child: Text(

title,
style: const TextStyle(color: Colors.black),

),
)

There is nothing technically wrong with it. The widget renders. The code is readable. Everyone understands what it does.

But architecturally, it is making a decision in the wrong place.

The widget is deciding that the surface must be white and the text must be black. That may be true today, but it is not the widget's job to know forever. Once dark mode enters the conversation, that decision belongs somewhere higher up: a theme, token system, semantic color layer, or at the very least a central color class.

So the goal was not to make the code prettier. It was to reduce the number of tiny places that would later need to “remember” how dark mode works.

Centralization is not the same as theming, but it is a start

The app already had an AppColors class, which was good. It meant the project had a place where visual constants could live.

The messy part was that some colors were already centralized while others were still written directly inside widgets. A few values already existed in AppColors, just under literal-style names. Some did not exist yet. Some were Flutter palette values like Colors.grey[400], which are convenient in the moment and annoying later.

The rule for the cleanup became very plain:

If the value already existed in AppColors, use it.

If it did not exist, add a static constant.

Do not rename the entire design system today.

Do not pretend this is a full dark mode implementation.

Just make sure the color literals stop leaking through the UI.

That last point mattered. It is tempting during a cleanup like this to turn it into a full semantic-token refactor:

AppColors.surfacePrimary
AppColors.surfaceElevated
AppColors.textPrimary
AppColors.textMuted
AppColors.borderDefault

Honestly, that is probably where the app should end up.

But today was not the day to redesign the whole color vocabulary. The immediate goal was containment. Before a color can become theme-aware, it needs to stop being scattered across a hundred widgets.

So even constants like this were useful:

class AppColors {
static const Color white = Color(0xFFFFFFFF);
static const Color black = Color(0xFF000000);
static const Color transparent = Color(0x00000000);

static const Color grey200 = Color(0xFFEEEEEE);
static const Color grey400 = Color(0xFFBDBDBD);
static const Color grey600 = Color(0xFF757575);

static const Color background = Color(0xFFFEFEFE);
static const Color border = Color(0xFFE8E8E8);
}

Not perfect. But centralized. And centralized is the first real step toward controllable.

The part that quietly mattered

One interesting detail was deciding what counted as a color problem.

A direct Color(0xFFAF6D57) in a widget is obviously a problem. It is a visual value hardcoded into UI code.

A dynamic parser like this is different:

Color(int.parse(cleanedHexValue, radix: 16));

That is not really a hardcoded design color. It is converting a value that came from elsewhere, probably an API or configuration payload. Centralizing that would be a different conversation: validation, fallback behavior, allowed palettes, maybe server-driven UI constraints.

So I left dynamic parsing alone and focused on literals: Colors.*, Color(0x...), and raw hex strings that represented fixed UI choices.

This is the kind of small boundary decision that does not look exciting in a diff, but it keeps a refactor from becoming a swamp.

Search and replace, with consequences

Most of the work was mechanical, but mechanical does not mean brainless.

For example, replacing Colors.grey with a color constant is not the same as replacing Colors.grey[400]. Flutter's material color swatches have shades, while a plain Color does not.

This was one of those tiny compiler reminders that the original code was relying on more than just a color value:

// Before
Paint()..color = Colors.grey.shade400;

// After
Paint()..color = AppColors.grey400;

That one line explains a lot. The old code depended on a MaterialColor API. The centralized version needed a concrete shade constant.

Another small gotcha: when doing broad replacements, the color class itself has to be protected. If a replacement pass rewrites the constants inside AppColors, you can accidentally create recursive constants like:

static const Color white = AppColors.white;

Which is both funny and very much not useful.

The analyzer caught that immediately. A mildly embarrassing moment, but also a good reminder: refactoring with tools is still refactoring. The compiler is part of the conversation.

Why this matters before dark mode

The easiest dark mode bugs are the ones you can see instantly: black text on a dark background, white cards floating awkwardly on a dark scaffold, disabled buttons with contrast that disappears.

The harder bugs are the ones caused by ownership confusion.

If every widget owns its own color decisions, then dark mode becomes a scavenger hunt. You change the theme, run the app, notice one broken screen, patch it, then find another. A bottom sheet here. A map overlay there. A custom painter somewhere else. Eventually you are debugging vibes.

Centralizing colors changes the shape of the work. It does not magically create dark mode, but it makes the next step sane. Instead of asking, “Where did this white come from?” you can ask, “Which token should this surface use?”

That is a much better question.

It also creates room for a future migration from raw constants to semantic ones. Today, AppColors.white may still be literal white. Later, a component might use AppThemeColors.surface(context) or a theme extension. That migration is much easier when the codebase is not full of anonymous hex values.

The small win

By the end of the cleanup, the app had no remaining direct Colors.* usage outside the central theme file, no direct Color(0x...) UI literals outside AppColors, and no raw hex color strings floating around in feature code.

The analyzer still had unrelated warnings, because real apps always have a little background noise. But the color cleanup itself was clean.

That felt like progress.

Not the shiny kind where a new feature appears on screen. More like the quieter kind where future work becomes less annoying because today's code stopped hiding decisions in random corners.

And honestly, that is a big part of mobile development. Some days you build screens. Some days you chase state bugs. Some days you move every Colors.white into one place because future-you deserves fewer headaches.

I Built a Complete Zomato-Style Food Delivery Platform in Flutter — Here's What I Learned

Sun, 10 May 2026 10:40:13 +0000

Just shipped Zesto — a full food delivery ecosystem with 4 Flutter
apps and a Firebase backend. Here's what the build taught me.

What's in the project

Customer App — OTP login, restaurant discovery, cart,
Razorpay payments, live driver tracking on Google Maps
Driver App — auto job assignment, step-by-step delivery
slider, background GPS foreground service
️ Restaurant App — real-time order dashboard, menu management
️ Admin Panel — Flutter Web, multi-city management

Backend: 20+Firebase Cloud Functions (Node.js 18)

3 Things That Bit Me Hard

Never trust client-side prices
My original placeOrder Cloud Function accepted grand_total from
the app. Anyone could send grand_total: 1 and get free food.
Fixed by recalculating everything server-side from Firestore menu
prices — never touching the client value.
Status string consistency across 4 apps
Flutter enums use camelCase by default (arrivedAtRestaurant).
Firestore stored snake_case (arrived_at_restaurant). Silent
mismatches everywhere. Lesson: standardize from day one and use
a safe parser that never throws on unknown values.
MobX reactions fire on every change — not just the first one
My HomeScreen reaction was pushing a new delivery screen every time
activeJob updated — including status changes while the driver was
already on the delivery screen. Three screens deep by the time the
order was delivered. A single boolean guard fixed it.

Tech Stack
Flutter 3.11+ · Dart · Firebase · Razorpay
Google Maps · MobX · Node.js 18 · GeoFlutterFire

The source code is available
If you're building something similar or want a real production
Flutter/Firebase codebase to learn from:
https://morningstar47jb.gumroad.com/l/tnevss
Demo video: https://youtube.com/shorts/rL2M5O5Tk50
Happy to answer any architecture questions in the comments.

The Coordinated BLoC Pattern in Flutter — A Practical Guide

Sat, 09 May 2026 08:12:03 +0000

The Coordinated BLoC Pattern in Flutter — A Practical Guide

This post is based on real production code. Every mistake documented here was hit in the wild, debugged, and understood the hard way.

At first, coordinating multiple BLoCs from initState feels harmless.

Then the screen grows.

Now:

some data depends on the authenticated user
some sections support silent refresh
some should show loading spinners
some should skip fetching if cached
pull-to-refresh has different behaviour than initial load

And suddenly your screen becomes the orchestration layer for half the app.

This article covers a pattern for extracting that orchestration into its own BLoC: the Coordination BLoC pattern.

More importantly, it covers the production mistakes this pattern introduces — especially the ones that fail silently.

What Problem Does This Solve?

Imagine a home screen that needs data from three different sources:

meditation groups
saadhna progress
user favourites

Each has its own BLoC.
Each BLoC is independent.
But they all need to be triggered together after the user's profile loads.

You also want smart refresh behaviour:

if data is fresh → silently refresh in background
if data is missing → show loading state
pull-to-refresh should force reload everything

Naively, you handle all of this inside initState:

@override
void initState() {
  super.initState();

  final profileState = context.read<ProfileBloc>().state;

  if (profileState is ProfileLoaded) {
    context.read<HomeMeditationGroupsBloc>()
        .add(FetchHomeMeditationGroups());

    context.read<SaadhnaBloc>()
        .add(FetchAllSaadhnaGroups());

    context.read<UserFavouritesBloc>()
        .add(FetchUserFavouriteMeditations(profileState.id));
  }
}

At first this works fine.

Then more conditions appear:

freshness checks
silent refreshes
auth dependencies
feature flags
retry behaviour
analytics
cross-bloc coordination

And now your screen knows too much about how loading works.

The Coordination BLoC pattern extracts orchestration logic into its own BLoC.

The screen fires one high-level event.
The coordination bloc decides what happens.

Mental Model

The coordination bloc owns:

when things load
why they load
which events should fire

The feature blocs still own:

data
business logic
rendering state

The coordination bloc orchestrates.
It does not aggregate UI state.

Architecture

                    ProfileBloc
                         │
                         ▼
             HomeCoordinationBloc
                         │
      ┌──────────────────┼──────────────────┐
      ▼                  ▼                  ▼
HomeMeditationBloc   SaadhnaBloc   UserFavouritesBloc

The coordination bloc becomes the single orchestration point for screen-level loading behaviour.

The screen no longer knows:

which blocs exist
which events they need
which dependencies they have
which refresh strategy they use

Implementation

1. Events

Keep events coarse-grained and intent-based.

sealed class HomeCoordinatorEvent {}

class HomeDataFetch extends HomeCoordinatorEvent {}

class HomeDataRefresh extends HomeCoordinatorEvent {}

Event Intent

Event	Meaning
`HomeDataFetch`	Smart load with freshness checks
`HomeDataRefresh`	Force reload everything

2. States

The coordination bloc does not own feature data.

Its responsibility is orchestration, not aggregation.

sealed class HomeCoordinatorState {}

class HomeCoordinatorInitialState
    extends HomeCoordinatorState {}

The UI still reads directly from feature blocs:

BlocBuilder<HomeMeditationGroupsBloc,
    HomeMeditationGroupsState>(
  builder: (context, state) {
    // render UI
  },
)

This separation is important.

The coordination bloc coordinates behaviour.
The feature blocs remain the source of truth.

3. The Coordination BLoC

The key idea

The screen fires one event:

HomeDataFetch()

The coordination bloc decides:

which blocs should refresh
whether data is stale
whether loading should be silent
whether user context is required

class HomeCoordinationBloc
    extends Bloc<HomeCoordinatorEvent,
        HomeCoordinatorState> {

  final HomeMeditationGroupsBloc
      homeMeditationGroupsBloc;

  final SaadhnaBloc saadhnaBloc;

  final UserFavouritesBloc
      userFavouritesBloc;

  final ProfileBloc profileBloc;

  late StreamSubscription profileSubscription;

  HomeCoordinationBloc({
    required this.homeMeditationGroupsBloc,
    required this.saadhnaBloc,
    required this.userFavouritesBloc,
    required this.profileBloc,
  }) : super(HomeCoordinatorInitialState()) {

    // Register handlers FIRST
    on<HomeDataFetch>(_fetchData);
    on<HomeDataRefresh>(_refetchData);

    // Trigger immediately if already loaded
    if (profileBloc.state is ProfileLoaded) {
      add(HomeDataFetch());
    }

    // Otherwise wait for profile load
    profileSubscription = profileBloc.stream
        .where((state) => state is ProfileLoaded)
        .take(1)
        .listen((_) {
          add(HomeDataFetch());
        });
  }

  void _fetchData(
    HomeDataFetch event,
    Emitter emit,
  ) {
    final userId =
        (profileBloc.state as ProfileLoaded).id;

    final isMeditationFresh =
        homeMeditationGroupsBloc.state
            is HomeMeditationGroupsFetched;

    final isSaadhnaFresh =
        saadhnaBloc.state
            is SaadhnaGroupsFetched;

    final isFavFresh =
        userFavouritesBloc.state
            is UserFavouritesFetched;

    homeMeditationGroupsBloc.add(
      isMeditationFresh
          ? SilentRefreshHomeMeditationGroups()
          : FetchHomeMeditationGroups(),
    );

    saadhnaBloc.add(
      isSaadhnaFresh
          ? RefetchAllSaadhnaGroups()
          : FetchAllSaadhnaGroups(),
    );

    userFavouritesBloc.add(
      isFavFresh
          ? RefetchUserFavouriteMeditations(userId)
          : FetchUserFavouriteMeditations(userId),
    );
  }

  void _refetchData(
    HomeDataRefresh event,
    Emitter emit,
  ) {
    final userId =
        (profileBloc.state as ProfileLoaded).id;

    homeMeditationGroupsBloc.add(
      RefreshHomeMeditationGroups(),
    );

    saadhnaBloc.add(
      FetchAllSaadhnaGroups(),
    );

    userFavouritesBloc.add(
      RefetchUserFavouriteMeditations(userId),
    );
  }

  @override
  Future<void> close() {
    profileSubscription.cancel();
    return super.close();
  }
}

Dependency Injection (GetIt)

This is where most production bugs come from.

sl.registerLazySingleton(
  () => HomeMeditationGroupsBloc(
    getMeditationGroupsByType: sl(),
  ),
);

sl.registerLazySingleton(
  () => SaadhnaBloc(
    getAllGroups: sl(),
  ),
);

sl.registerLazySingleton(
  () => UserFavouritesBloc(),
);

sl.registerLazySingleton(
  () => HomeCoordinationBloc(
    homeMeditationGroupsBloc: sl(),
    saadhnaBloc: sl(),
    userFavouritesBloc: sl(),
    profileBloc: sl(),
  ),
);

BLoC Providers

BlocProvider<UserFavouritesBloc>(
  create: (context) => sl<UserFavouritesBloc>(),
),

BlocProvider<HomeMeditationGroupsBloc>(
  create: (context)
      => sl<HomeMeditationGroupsBloc>(),
),

BlocProvider<SaadhnaBloc>(
  create: (context) => sl<SaadhnaBloc>(),
),

BlocProvider<HomeCoordinationBloc>(
  create: (context)
      => sl<HomeCoordinationBloc>(),
),

The Screen

The screen now knows nothing about orchestration.

@override
Widget build(BuildContext context) {
  return LiquidPullToRefresh(
    onRefresh: () async {
      context.read<HomeCoordinationBloc>()
          .add(HomeDataRefresh());
    },
    child: ListView(
      children: [
        BlocBuilder<
            HomeMeditationGroupsBloc,
            HomeMeditationGroupsState>(
          builder: (context, state) {
            // render section
          },
        ),
      ],
    ),
  );
}

Mistakes to Not Make

Mistake 1: Registering Handlers After Calling `add()`

This causes a runtime Bad state error.

// WRONG
HomeCoordinationBloc(...)
    : super(HomeCoordinatorInitialState()) {

  if (profileBloc.state is ProfileLoaded) {
    add(HomeDataFetch());
  }

  on<HomeDataFetch>(_fetchData);
}

// CORRECT
HomeCoordinationBloc(...)
    : super(HomeCoordinatorInitialState()) {

  on<HomeDataFetch>(_fetchData);

  if (profileBloc.state is ProfileLoaded) {
    add(HomeDataFetch());
  }
}

The BLoC library checks for a handler immediately when add() is called.

Constructor order matters.

Mistake 2: Using `registerFactory`

This bug is especially nasty because everything appears to work — except the UI never updates.

// WRONG
sl.registerFactory(
  () => HomeMeditationGroupsBloc(...),
);

What happens:

Coordination bloc gets Instance A
UI listens to Instance B
Events fire correctly
Data loads correctly
UI never rebuilds

Two blocs.
Two states.
Zero visible errors.

// CORRECT
sl.registerLazySingleton(
  () => HomeMeditationGroupsBloc(...),
);

Rule

Any bloc referenced by a coordination bloc should usually be a singleton.

Mistake 3: Forgetting to Cancel Stream Subscriptions

// WRONG
@override
Future<void> close() => super.close();

// CORRECT
@override
Future<void> close() {
  profileSubscription.cancel();
  return super.close();
}

Otherwise the subscription can attempt to call add() on a closed bloc.

Mistake 4: Forgetting `.take(1)`

Without .take(1):

profileBloc.stream
    .where((state) => state is ProfileLoaded)
    .listen((_) => add(HomeDataFetch()));

Every future ProfileLoaded state retriggers fetches.

That can create phantom refreshes after:

token refreshes
profile edits
re-authentication

Usually you only want the first load:

profileBloc.stream
    .where((state) => state is ProfileLoaded)
    .take(1)
    .listen((_) => add(HomeDataFetch()));

Mistake 5: Mixing `GetIt` and `context.read`

// Confusing and unnecessary
_homeCoordinationBloc =
    GetIt.instance<HomeCoordinationBloc>();

Then later:

context.read<HomeCoordinationBloc>()

Pick one access pattern.

If the bloc comes from BlocProvider,
prefer context.read<X>().

Mistake 6: Leaving Half the Logic in the Screen

Once you introduce a coordination bloc, commit to it.

// Split ownership
context.read<HomeCoordinationBloc>()
    .add(HomeDataFetch());

context.read<SaadhnaBloc>()
    .add(FetchAllSaadhnaGroups());

Now orchestration lives in two places.

That is worse than either approach alone.

The Hidden Cost: Forced Singletons

This pattern introduces a real architectural tradeoff.

Your feature blocs now live for the entire app lifecycle.

That means:

cached state survives navigation
previous data persists
memory usage increases
state does not automatically reset

This is usually correct for:

home feeds
dashboards
cached content
long-lived tabs

This is usually dangerous for:

forms
temporary workflows
checkout flows
wizard-style screens

Do not accidentally turn screen-scoped state into app-scoped state.

When To Use This Pattern

Use it when:

3+ blocs must coordinate together
another bloc's state gates loading
loading logic contains real conditions
orchestration is reused across screens
refresh behaviour is non-trivial

When NOT To Use It

Do not use it when:

you're only triggering 1-2 blocs
coordination is just sequential add() calls
the screen logic is still simple
feature blocs should remain screen-scoped

In those cases, a BlocListener is simpler and cleaner.

The Simpler Alternative

For smaller flows:

BlocListener<ProfileBloc, ProfileState>(
  listenWhen: (prev, curr) =>
      curr is ProfileLoaded &&
      prev is! ProfileLoaded,

  listener: (context, state) {
    final userId =
        (state as ProfileLoaded).id;

    context.read<HomeMeditationGroupsBloc>()
        .add(FetchHomeMeditationGroups());

    context.read<SaadhnaBloc>()
        .add(FetchAllSaadhnaGroups());

    context.read<UserFavouritesBloc>()
        .add(
          FetchUserFavouriteMeditations(
            userId,
          ),
        );
  },

  child: YourScreen(),
)

This solution:

is smaller
avoids singletons
avoids stream subscriptions
avoids an extra bloc entirely

Start here first.

Graduate to coordination blocs only when the orchestration becomes genuinely complex.

Summary

	Coordination BLoC	BlocListener
Complexity	High	Low
Testability	High	Medium
Reusability	High	Low
Singleton Requirement	Usually Yes	No
Best For	Complex orchestration	Simple fan-out logic

The Coordination BLoC pattern is a real solution for real complexity.

The mistake is introducing it too early.

Start simple.
Escalate only when the orchestration actually demands it.

When a Button Should Do More Than Close

Thu, 07 May 2026 16:33:53 +0000

Some days in Flutter are not about huge refactors or dramatic crashes. Some days are about a button that says one thing and does another.

Today’s task looked harmless: clean up a few dialog buttons in an event-planning mobile app. The dialogs were already showing at the right moments. The UI looked fine enough. The copy was clear.

But then I tapped the buttons mentally and noticed the problem: most of them just closed the dialog.

That is not always wrong. Sometimes a dialog is only a nudge. Sometimes “Okay” really does mean “go away, I understand.” But if a button says “View Pending Tasks” and then only pops the modal, that is a tiny betrayal. Not catastrophic, not release-blocking, just one of those product papercuts that makes an app feel less intentional.

So the day became less about button styling and more about answering a deceptively annoying question:

The dialog was innocent

The dialog components themselves were simple Flutter widgets. A few icons, some copy, and an ElevatedButton at the bottom.

The original pattern looked roughly like this:

class DayDialog extends StatelessWidget {
  const DayDialog({super.key});

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        Navigator.pop(context);
      },
      child: const Text("Let's Go"),
    );
  }
}

There is nothing technically broken about that. It compiles. It works. The dialog closes.

But the app had dialogs with stronger intent:

“It’s D-Day” should take the user to the event happening today.
“You’ve got tasks waiting” should take the user somewhere useful for those tasks.
“Missed something?” should open notifications.
“One step closer” might honestly just dismiss, because it is more encouragement than navigation.

That last distinction ended up mattering. Not every button needs to become a route change just because we are in a “make buttons useful” mood.

The first useful clue: don’t make the dialog smart

The tempting mistake would have been to import screens into every dialog and let the dialog figure out where to navigate.

That would work for about five minutes.

Then the dialog layer would start knowing about event models, notification screens, task picking rules, dashboard cache, route transitions, and probably someone’s lunch order if I looked away long enough.

The cleaner move was to keep the dialogs dumb and let the screen that shows them inject behavior.

So the dialog becomes callback-driven:

class DayDialog extends StatelessWidget {
  final VoidCallback? onLetsGo;

  const DayDialog({
    super.key,
    this.onLetsGo,
  });

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        if (onLetsGo != null) {
          onLetsGo!();
          return;
        }

        Navigator.pop(context);
      },
      child: const Text("Let's Go"),
    );
  }
}

This is a small change, but it keeps the boundary clean:

The dialog owns presentation.
The home screen owns app state.
Navigation is decided where the relevant state already exists.

Flutter makes it very easy to blur those lines because BuildContext is everywhere. That convenience is lovely until every widget becomes slightly aware of the entire app.

D-Day was the easy one

The D-Day dialog had a nice property: the event it referred to was already known.

The home screen was computing the earliest upcoming event and storing it as a mapped event model. The D-Day eligibility check was based on that same event date. In plain terms, if the app says “your event starts now,” then the event to open should be the earliest event that made that condition true.

That gave us a clean action:

DayDialog(
  onLetsGo: () {
    final event = earliestEvent;
    Navigator.of(dialogContext).pop();

    if (event == null || !mounted) return;

    Navigator.of(context).push(
      MaterialPageRoute(
        builder: (_) => EventDetailsScreen(event: event),
      ),
    );
  },
);

There are two contexts here, and that is not accidental.

The dialog builder gives a dialogContext, which is the safest context for popping the dialog. The screen’s own context is then used for pushing the next route.

Could one context have worked? Probably. But “probably” is not my favorite navigation strategy, especially around dialogs. Flutter navigation bugs tend to wait until a specific route stack shape appears, then quietly ruin your afternoon.

The task dialog was less polite

The pending task dialog sounded simple:

Cool. Open pending tasks.

Except there was no single “pending tasks screen.” Also, tasks belonged to different events.

A dashboard task had enough information to know that it was incomplete and which event it belonged to, but the event details screen needed a fuller event model. So the app had two related but different pieces of state:

dashboard task summaries
full mapped events from the events response

That meant the button needed a selection rule.

We considered a few choices:

open the calendar, which is safe but broad
build a grouped pending tasks view, which is better UX but more work
open the event containing the next task needing attention

The last option felt like the best daily tradeoff. It makes the button do something concrete without inventing a new screen.

The rule became:

Find incomplete tasks.
Prefer the nearest upcoming incomplete task.
If all incomplete tasks are overdue, pick the most recently overdue one.
Find the event that owns that task.
Open event details.
If the event cannot be found, fall back to the calendar.

That sounds like a lot for one button, but it is really just product intent expressed as code.

TaskSummary? findTaskNeedingAttention(List<TaskSummary> tasks) {
  final pending = tasks.where((task) => !task.isCompleted).toList();
  if (pending.isEmpty) return null;

  final now = DateTime.now();

  final upcoming = pending
      .where((task) => task.date != null && !task.date!.isBefore(now))
      .toList()
    ..sort((a, b) => a.date!.compareTo(b.date!));

  if (upcoming.isNotEmpty) return upcoming.first;

  final overdue = pending.where((task) => task.date != null).toList()
    ..sort((a, b) => b.date!.compareTo(a.date!));

  if (overdue.isNotEmpty) return overdue.first;

  return pending.first;
}

The fallback mattered to me. Real mobile state is messy. Maybe the dashboard response has a task whose event is missing from the events response. Maybe caching gives you a slightly stale combination. Maybe the backend shape changes in some tiny way on a tired Tuesday.

In those cases, the app should still take the user somewhere useful instead of turning the button into a dead end.

The callback pattern held up

Once the dialog had a callback, the home screen could own the messy part:

PendingTasksDialog(
  onViewPendingTasks: () {
    final event = findPendingTaskEvent();
    Navigator.of(dialogContext).pop();

    if (!mounted) return;

    if (event == null) {
      openCalendarScreen();
      return;
    }

    Navigator.of(context).push(
      MaterialPageRoute(
        builder: (_) => EventDetailsScreen(event: event),
      ),
    );
  },
);

That made the dialog more reusable and the navigation more honest.

I also had to make sure the mapped event list was cached alongside the rest of the home state. Otherwise the behavior would work after a fresh fetch but fail or degrade after cached dashboard state restored. This is exactly the kind of small state detail that does not announce itself loudly. It just becomes a weird “works sometimes” bug later.

I do not enjoy future-me debugging “works sometimes.” Future-me is busy enough.

The button we left alone

The most interesting decision might have been the one where we did nothing.

There was a “One step closer” dialog shown after the user completed more tasks. The button said “Keep Planning.” At first, it looked like another candidate for navigation.

But after thinking through it, dismissing the dialog actually made sense.

That dialog is not saying “go inspect this exact object.” It is more like a little celebration. The user has made progress; the app is acknowledging it; closing the dialog returns them to whatever planning context they were already in.

Changing that button to navigate somewhere might have made the app feel jumpy. Useful is good. Over-eager is not.

This was a nice reminder that consistency does not mean every button does the same category of thing. It means every button does what its label and context imply.

Small Flutter details that mattered

A few practical details stood out:

Navigator.pop should close the dialog before pushing the next screen.
Use the dialog’s context to pop the dialog route.
Use the parent screen’s context to push the app route.
Check mounted before navigating after state-dependent callbacks.
Keep UI widgets dumb when the state lives somewhere else.
Cache all derived state needed by a callback, not only what the UI visibly renders.

None of those are groundbreaking. They are just the little edges that separate “it works in my test tap” from “this behaves reliably in the app.”

The quiet lesson

Today’s work started with dialog buttons and ended up being about intent.

A button label is a contract. If it says “View Notifications,” it should not merely close. If it says “View Pending Tasks,” it should make a reasonable decision about which task needs attention. If it says “Keep Planning,” sometimes the best behavior is simply to get out of the way.

The technical implementation was not huge: a couple of callbacks, a mapped event list, a task selection helper, and a fallback route. But the thinking behind it was the useful part.

Flutter gives us the tools to wire screens together very quickly. The harder part is deciding where the knowledge should live, what the user expects, and how much logic a tiny button deserves.

Today, one tiny button deserved more than Navigator.pop(context).

Another one did not.

That balance was the actual feature.

Why Your Flutter UI Freezes: Understanding Async, Await, Compute & Isolates

Thu, 07 May 2026 11:28:09 +0000

You're building a Flutter app. Everything feels smooth — taps register instantly, animations glide, scrolling is butter.

Then one day you load a large dataset. Maybe 15,000 transactions from a crypto API. Maybe a chunky image processing job. Maybe just a fat JSON response.

And suddenly: the UI freezes. Buttons stop responding. Animations stutter. Scrolling locks up. Users notice.

Your first instinct? Blame async/await.

Bad news: async/await is innocent. The real culprit is something more fundamental — and once you understand it, you'll never guess at Flutter performance problems again. You'll engineer around them.

The Uncomfortable Truth: Dart Is Single-Threaded

Every Flutter app runs inside a Dart isolate. That isolate has:

Its own memory
Its own event loop
One execution thread

One. Single. Thread.

Picture it as a conveyor belt:

→ RENDER FRAME → HANDLE TAP → RENDER FRAME → YOUR HEAVY WORK → RENDER FRAME →

The belt moves forward only when each item finishes. If "YOUR HEAVY WORK" takes 3 seconds, the belt stops for 3 seconds. No rendering. No touch events. Nothing.

That's your UI freeze. That's jank.

The Biggest Misconception in Flutter Development

Here's what most developers assume:

await heavyCalculation(); // "this runs in the background, right?"

Wrong.

async/await does not move work to another thread. It does not create parallelism. It does not make your code run somewhere else.

What it actually means is:

"Pause this function here. Resume it later when the Future completes."

That's it. That's the whole trick.

To prove it — this code freezes your UI completely, even with async/await:

Future<void> freezeUI() async {
  for (var i = 0; i < 1000000000; i++) {} // CPU grinding on the UI thread
}

// Calling this:
await freezeUI(); // Still freezes. async didn't save you.

The work is still running on the same isolate as your UI. await just made it look like it wouldn't.

So What Does Async-Await Actually Do Well?

Async shines when your code is waiting, not working.

When you make a network request:

final response = await http.get(Uri.parse('https://api.example.com/data'));

Here's what actually happens under the hood:

Dart initiates the request
Dart tells the OS: "ping me when this finishes"
The isolate is now free — it goes back to rendering, handling taps, running animations
When the response arrives, Dart resumes your function from where it left off

No blocking. No freezing. The isolate was idle anyway — it was waiting on the network, not computing.

This is non-blocking I/O. And async/await handles it beautifully.

The problem only starts when you stop waiting and start working.

The Dart Event Loop (And Why It Matters)

To really understand async behavior, you need to know how Dart schedules work.

Dart's event loop has two queues:

Microtask Queue (High Priority)

Used for:

Future continuations (what runs after an await)
scheduleMicrotask() calls

Event Queue (Normal Priority)

Used for:

Timer callbacks
Network/IO completions
Gesture events
Platform messages

The loop runs like this:

1. Run all synchronous code
2. Drain every pending microtask
3. Execute one event from the event queue
4. Repeat forever

This ordering has a real-world consequence. Here's a classic puzzle:

void main() {
  print("A");                                    // sync
  Future(() => print("B"));                      // event queue
  scheduleMicrotask(() => print("C"));           // microtask queue
  print("D");                                    // sync
}

Output:

A
D
C
B

Why? Because:

A and D are synchronous — they run first, in order
C is a microtask — it runs before any events
B is in the event queue — it runs last

Knowing this helps you reason about execution order, debug subtle timing bugs, and understand why async/await resumptions feel immediate (they're microtasks).

The JSON Parsing Trap

Here's where developers get burned all the time.

Your app fetches data. The network call is fine — async, non-blocking, smooth. But then:

final response = await http.get(url);               // non-blocking, isolate is free
final data = jsonDecode(response.body);             // CPU-heavy, blocks the isolate

jsonDecode on a small payload? No problem. On 15,000 transaction records? That single line can block your UI for 2–4 seconds.

The network call wasn't your enemy. The parsing was.

This is the trap: the operation after await can still freeze your UI if it's CPU-intensive.

The Fix: Isolates

An isolate is an independent Dart execution environment. It has:

Its own memory heap (completely separate from your UI isolate)
Its own event loop
Its own thread

Unlike OS threads, isolates cannot share memory. This eliminates entire classes of bugs — no race conditions, no mutex deadlocks, no shared-state corruption. Instead, isolates communicate by passing messages.

Main Isolate                    Worker Isolate
─────────────                   ──────────────
UI rendering                    JSON parsing
Touch handling       ←──────→   Image processing
Animations          (messages)  Heavy computation

While the worker isolate grinds through CPU work, your UI isolate keeps rendering at 60fps.

`compute()`: Isolates Without the Ceremony

Spawning a raw isolate involves some boilerplate. For one-off tasks, Flutter gives you compute():

// Before: freezes UI
final transactions = jsonDecode(response.body);

// After: runs in a separate isolate, UI stays smooth
final transactions = await compute(parseTransactions, response.body);

Where parseTransactions is a top-level or static function:

List<Transaction> parseTransactions(String rawJson) {
  final decoded = jsonDecode(rawJson) as List;
  return decoded.map((e) => Transaction.fromJson(e)).toList();
}

compute() under the hood:

Spawns a new isolate
Sends your data to it (via message passing — it gets copied)
Runs your function
Returns the result to the main isolate
Destroys the worker isolate

One function call. UI stays responsive. Task done in parallel.

When `compute()` Isn't Enough: Persistent Isolates

compute() is great for one-shot jobs. But spawning and destroying isolates has overhead. If you're doing continuous background work — like a live transaction feed, streaming parser, or on-device ML inference — you want a persistent isolate.

// Pseudo-code for a long-running isolate
final receivePort = ReceivePort();
final isolate = await Isolate.spawn(backgroundWorker, receivePort.sendPort);

receivePort.listen((message) {
  // Handle result from background isolate
  setState(() => _data = message);
});

Use persistent isolates when:

You're processing a continuous stream of data
You're running local AI/ML models
You have a background sync engine
The spawning overhead of compute() becomes measurable

The Decision Framework

Every time you write async code, ask: am I waiting or working?

Scenario	Use
API call / network request	`async/await`
Database read/write	`async/await`
File I/O	`async/await`
Timer / delay	`async/await`
JSON parsing (large)	`compute()`
Image processing	`compute()`
Encryption / hashing	`compute()`
One-off heavy computation	`compute()`
Streaming data parser	Persistent Isolate
On-device ML inference	Persistent Isolate
Background sync engine	Persistent Isolate

Real-World Example: Crypto Wallet Transaction Feed

Let's put it all together with a realistic scenario.

Your wallet app fetches 15,000 transactions. Naïve implementation:

// Freezes UI for multiple seconds
Future<void> loadTransactions() async {
  final response = await http.get(transactionsUrl);   // fine
  final txs = jsonDecode(response.body);              //  blocks here
  setState(() => _transactions = txs);
}

Better:

// UI stays responsive throughout
Future<void> loadTransactions() async {
  final response = await http.get(transactionsUrl);                    // non-blocking
  final txs = await compute(parseTransactions, response.body);         // off-thread
  setState(() => _transactions = txs);                                 // back on UI thread
}

List<Transaction> parseTransactions(String json) {
  return (jsonDecode(json) as List)
      .map((e) => Transaction.fromJson(e))
      .toList();
}

The user never sees a freeze. Scrolling stays smooth at 60fps while thousands of transactions parse in the background.

Common Myths, Killed

"Async/await makes my code multithreaded"
No. It handles asynchronous waiting. Multithreading requires isolates.

"If I put await before it, it won't block the UI"
Only if the work is I/O-bound. CPU-heavy code blocks regardless of await.

"compute() is some kind of magic optimization"
It's just a thin wrapper around isolate spawning. The magic is the isolate, not the function.

"Dart can only use one CPU core"
False. Each isolate can run on its own OS thread. Dart can use all your cores through isolates.

The Mental Model That Fixes Everything

Burn this into your brain:

async/await  →  for WAITING
isolates     →  for WORKING

That's the whole framework. Every Flutter performance bug related to async ultimately comes down to confusing these two. Once you stop conflating them, you stop guessing — and start building apps that are genuinely fast.

Your UI thread should only wait. Never grind.

Everything about Stateful & Stateless widgets in Flutter

Mon, 04 May 2026 03:34:50 +0000

Flutter's widget system looks deceptively simple on the surface — everything is a widget, you compose them, and the UI appears. But once you go deeper, you realize Flutter made a very deliberate architectural decision by splitting widgets into two kinds: Stateless and Stateful. Understanding why that split exists, and how the machinery behind it works, is what separates developers who use Flutter from developers who truly understand it.

Before distinguishing the two, it's worth being precise about what a widget actually is in Flutter's model.

A widget is an immutable description of a piece of UI. That's it. It's a configuration object — a blueprint. It doesn't draw anything, it doesn't hold layout state, it doesn't live on screen. It just describes what should exist.

Flutter maintains three separate trees to actually make that description come alive:

Widget tree — The lightweight, immutable descriptions you write in code. Rebuilt frequently.
Element tree — The long-lived, mutable counterpart to each widget. Elements persist across rebuilds and act as the glue between widgets and render objects.
RenderObject tree — The heavy, layout-and-paint layer. This is what actually measures, positions, and renders pixels.

This separation is critical to Flutter's performance. Rebuilding the widget tree is cheap because widgets are just Dart objects with a few fields. The element and render object trees, which are expensive to create, are preserved and updated incrementally.

Stateless Widgets

A StatelessWidget is a widget whose entire output is determined solely by its constructor arguments. Given the same inputs, it will always produce the same widget tree — there is no internal state that can change between builds.

class GreetingCard extends StatelessWidget {
  final String name;
  final String message;

  const GreetingCard({super.key, required this.name, required this.message});

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Hello, $name'),
        Text(message),
      ],
    );
  }
}

Flutter calls build() on a stateless widget when its parent rebuilds and passes it new configuration. The widget itself has no lifecycle beyond that single build() call — no initialization, no teardown, no reactive hooks.

The `const` Optimization

Stateless widgets shine when paired with const constructors. When Flutter encounters a const widget in a rebuild, it can short-circuit the entire subtree — it knows the widget is identical to the previous one (same type, same arguments, canonicalized at compile time), so there's nothing to diff.

// Flutter will never rebuild this subtree unless the parent explicitly changes it
const Icon(Icons.star, color: Colors.amber, size: 24);

For UI elements that are truly static — icons, labels, decorative containers — const is a free performance win. Make it a habit to use const wherever possible and let the Dart analyzer enforce it with the prefer_const_constructors lint.

Stateful Widgets

A StatefulWidget is for UI that needs to change over time based on user interaction, async results, animations, or any other runtime event. The key design decision Flutter made here is that the widget and its state are two separate objects.

class Counter extends StatefulWidget {
  const Counter({super.key});

  @override
  State<Counter> createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int _count = 0;

  @override
  Widget build(BuildContext context) {
    return TextButton(
      onPressed: () => setState(() => _count++),
      child: Text('Count: $_count'),
    );
  }
}

Why separate them? Because widgets are immutable and short-lived, but state needs to persist. When Flutter rebuilds the Counter widget, it creates a brand-new Counter object — but the _CounterState instance that holds _count is kept alive by the element tree. The element simply calls widget.build() on the new widget description while retaining the existing State object beneath it.

The Stateful Lifecycle

State objects have a full lifecycle managed by the Flutter framework. Understanding each phase is essential for writing correct, leak-free Flutter code.

`createState()`

Called on the widget (not the state) to create the associated State object. This happens exactly once — when the widget is first inserted into the tree.

@override
State<MyWidget> createState() => _MyWidgetState();

`initState()`

The first method called on the State object after it's created. This is where you perform one-time initialization — subscribing to streams, setting up animation controllers, making initial API calls.

@override
void initState() {
  super.initState(); // Always call super first
  _controller = AnimationController(vsync: this, duration: const Duration(milliseconds: 300));
  _fetchInitialData();
}

initState() runs before the first build, and context is available but restricted here — you cannot call context-dependent operations like Navigator.of(context) from initState(). Use didChangeDependencies() or a post-frame callback for that.

`didChangeDependencies()`

Called immediately after initState(), and again whenever an InheritedWidget that this state object depends on changes. For example, if your widget reads from Theme.of(context) or a custom InheritedWidget, and that data changes, didChangeDependencies() fires before the next build.

@override
void didChangeDependencies() {
  super.didChangeDependencies();
  // Safe to use context-dependent APIs here
  final locale = Localizations.localeOf(context);
  _updateForLocale(locale);
}

`build()`

The only required override. Called every time the state is marked dirty — after setState(), after didChangeDependencies(), after didUpdateWidget(), and during the initial render. Must be pure and free of side effects.

`setState()`

The mechanism for signaling that internal state has changed and the widget needs to rebuild.

setState(() {
  _count++;
  _isLoading = false;
});

When you call setState(), Flutter marks the element as dirty. It doesn't trigger an immediate rebuild — instead, it schedules a frame. At the start of the next frame, Flutter walks the element tree, finds all dirty elements, and calls build() on each of them. The widget returned by build() is then reconciled against the previous widget using the element tree (more on this below).

`didUpdateWidget()`

Called when the parent rebuilds and passes a new widget instance to this state's element. The old widget is passed as an argument, giving you a chance to react to configuration changes.

@override
void didUpdateWidget(covariant MyWidget oldWidget) {
  super.didUpdateWidget(oldWidget);
  if (widget.userId != oldWidget.userId) {
    _fetchDataForUser(widget.userId);
  }
}

This is the correct place to respond to external prop changes — not initState(), which only runs once.

`deactivate()`

Called when the State object is temporarily removed from the tree — for example, when a widget is moved to a different subtree location using a GlobalKey. This is uncommon in everyday Flutter code, but important to know.

`dispose()`

Called when the State object is permanently removed from the tree. This is where you clean up resources — cancel timers, close streams, dispose animation controllers, remove listeners.

@override
void dispose() {
  _controller.dispose();
  _scrollController.dispose();
  _subscription.cancel();
  super.dispose(); // Always call super last
}

Forgetting to dispose() resources is one of the most common sources of memory leaks in Flutter apps.

How Reconciliation Actually Works

When a dirty element rebuilds, it gets a new widget from build(). Flutter then needs to decide: does the existing child element still apply, or does it need to be replaced?

Flutter checks two things in order:

Type — Is the new widget the same runtime type as the widget the element currently holds?
Key — If a key is present, does it match?

If both match, Flutter reuses the element and simply updates its widget reference. The underlying RenderObject is updated in place — expensive layout state is preserved.

If either differs, Flutter deactivates the old element, creates a new one, and mounts it. For stateful widgets, this means the State is disposed and a new one is created from scratch.

// Scenario: parent conditionally renders one of two widgets
if (_showA)
  const WidgetA()   // Type: WidgetA
else
  const WidgetB()   // Type: WidgetB — new element, old state discarded

Keys: Making Reconciliation Precise

By default, Flutter reconciles children by type and position. For static, fixed-size lists this works perfectly. But for dynamic, reorderable, or filtered lists, positional matching breaks down.

// Imagine these items get reordered from [A, B] to [B, A]
// Without keys, Flutter sees: position 0 = same type, position 1 = same type
// It reuses the same elements — the state of A bleeds into B's position
Column(
  children: [
    TodoItem(label: 'B'),
    TodoItem(label: 'A'),
  ],
)

Keys tell Flutter explicitly which element corresponds to which widget, regardless of position.

`LocalKey`

Scoped to siblings within the same parent. The common variants are:

ValueKey<T> — keyed by a value (most common, use with IDs or strings)
ObjectKey — keyed by object identity
UniqueKey — generates a new key every time (forces recreation — use deliberately)

ListView(
  children: _todos.map((todo) =>
    TodoItem(key: ValueKey(todo.id), label: todo.label)
  ).toList(),
)

Now when items reorder, Flutter correctly matches each TodoItem to its element by ID, preserving the right state in the right place.

`GlobalKey`

Unique across the entire widget tree. A GlobalKey lets you access a widget's State, BuildContext, or RenderObject from anywhere in the app.

final _formKey = GlobalKey<FormState>();

// Later:
if (_formKey.currentState!.validate()) {
  _formKey.currentState!.save();
}

GlobalKey is powerful but expensive — Flutter maintains a global registry for them. Avoid using them as a shortcut to reach into widget state; prefer proper state management patterns for that. Use GlobalKey when you genuinely need framework-level access — form validation, imperative scroll control, or moving a subtree across the tree while preserving its state.

The `mounted` Property and Async Safety

Every State object has a mounted boolean. It becomes true after initState() runs and transitions to false after dispose(). It exists to solve a specific and common problem: calling setState() after the widget has been removed from the tree.

Future<void> _loadData() async {
  final result = await repository.fetchItems(); // async gap — widget may be disposed here

  setState(() => _items = result); //  throws if widget was already disposed
}

The safe pattern:

Future<void> _loadData() async {
  final result = await repository.fetchItems();

  if (mounted) {
    setState(() => _items = result);
  }
}

This is especially important in scenarios where a user navigates away while a network call is still in flight, or when a parent removes the widget before the async operation completes. The mounted check is a lightweight guard that prevents both the exception and the logical error of mutating dead state.

When to Use Which

The choice is usually straightforward once you internalize the rule:

If the widget can fully describe its UI from its constructor arguments alone, use StatelessWidget. If it needs to track any internal state that changes over time, use StatefulWidget.

Some practical heuristics:

Pure display widgets (cards, labels, icons, decorative layouts) → StatelessWidget with const
Anything with user interaction that changes appearance (toggles, counters, form fields) → StatefulWidget
Animations → StatefulWidget with SingleTickerProviderStateMixin
Widgets that only receive state from above (via constructor or InheritedWidget) and just render it → StatelessWidget

It's also worth noting that the separation isn't just about correctness — it's about communicating intent. A StatelessWidget signals to every reader of your code: this widget has no internal moving parts. That's a strong, useful guarantee.

Putting It All Together

Flutter's architecture makes more sense when you see the whole picture at once:

Widgets are cheap, immutable blueprints. Rebuilt frequently, thrown away without ceremony.
Elements are the persistent, mutable objects that hold the tree together. They match incoming widgets to existing state.
RenderObjects are expensive and preserved. Updated in place whenever possible.
Stateful widgets get a separate State object, anchored to an element, that survives widget rebuilds.
setState() marks elements dirty and schedules a frame — not an immediate rebuild.
Reconciliation by type and key determines whether to reuse or replace elements.
Keys make that reconciliation correct when position alone isn't enough.
mounted is your safety net for async operations that outlive the widget.

Every Flutter performance tip — minimizing rebuilds, using const, lifting state appropriately, keying lists — traces back to understanding these fundamentals. Once the model is clear, the best practices follow naturally.

The Selfie Was Fine. The Pixels Were Sideways.

Fri, 01 May 2026 15:29:12 +0000

I spent part of today staring at a selfie that looked completely normal in the app until it became a profile photo.

That sentence sounds harmless. It was not harmless.

The face verification flow looked fine while running. The camera preview was upright. The liveness checks passed. The user smiled, turned left, turned right, looked up, looked down, and the app happily uploaded the images. Then the first image, the nice centered smiling one, became the user's display picture.

And suddenly the user was lying sideways.

Head on the right. Neck on the left. The kind of bug where the UI looks innocent, the backend looks innocent, and the image itself is quietly doing the wrong thing.

The suspicious part was not the avatar

My first instinct was to look at the profile image rendering. Maybe the avatar widget was doing something odd. Maybe the network image package ignored metadata. Maybe the backend transformed the image. Maybe some storage layer stripped EXIF orientation.

But the avatar was boring in the best possible way. It received a URL and rendered it with BoxFit.cover. No transforms. No rotation. No custom painting. Nothing dramatic.

The face verification flow was more interesting.

The app was using the camera stream for liveness detection. Each frame went through ML Kit face detection, and once a rule was stable enough, we captured the image for that rule. The first rule was the centered smile, which later became the display picture.

That gave the bug a shape:

preview upright
ML Kit detection working
saved/uploaded image rotated
all captured images rotated the same way

That combination usually means the display layer and detection layer know about orientation, but the saved pixels do not.

The camera stream was telling the truth, just not the truth I wanted

The important detail was that the capture path was not using takePicture().

Instead, the flow converted the exact CameraImage stream frame into a PNG. The motivation made sense: use the precise frame that satisfied the face rule. No waiting for the camera to stop streaming, no second capture after the user moved slightly, no autofocus/flicker delay. It is a tempting approach, and honestly, I still like the intent.

The rough shape looked like this:

final imagePath = await _captureFromStreamFrame(streamFrame);

Inside that helper, Android NV21 bytes were converted into BGRA pixels, then encoded as a PNG:

ui.decodeImageFromPixels(
  bgraBytes,
  image.width,
  image.height,
  ui.PixelFormat.bgra8888,
  (img) => completer.complete(img),
);

final uiImage = await completer.future;
final byteData = await uiImage.toByteData(
  format: ui.ImageByteFormat.png,
);

This is where Flutter politely allowed me to shoot myself in the foot.

Raw camera stream frames are not necessarily in the same orientation as the preview on screen. On Android especially, the camera sensor often has a native orientation that is effectively landscape relative to the way the user holds the phone. The preview widget handles that. ML Kit also gets rotation metadata, so detection can still work.

But if you manually turn the raw bytes into a PNG, nobody magically rotates those pixels for you.

You get the sensor's version of reality.

And the sensor's version of reality had my user's head rotated 90 degrees.

The part that made it slightly annoying

The obvious fix was "rotate the image."

The less obvious question was: rotate it which way?

This is where mobile camera work always gets a little slippery. You are dealing with a few concepts that sound related but are not interchangeable:

sensor orientation
device orientation
preview orientation
front-camera mirroring
saved image orientation
EXIF metadata, if you are saving JPEGs
actual pixel rotation, if you are writing PNGs

In this flow we were writing PNGs from raw pixels, so EXIF was not going to save us. The pixels themselves needed to be corrected.

The first attempt used the inverse of the camera sensor orientation:

return (360 - sensorOrientation) % 360;

It was a reasonable guess. It was also wrong for the tested device.

The image moved from sideways to upside down. Progress, technically. Emotionally, less so.

That test was useful though, because it proved two things immediately:

We were definitely fixing the right part of the pipeline.
The rotation direction needed to be flipped.

So the final working version used the reported sensor orientation directly:

int _streamFrameRotationDegrees({
  required int sensorOrientation,
}) {
  if (!Platform.isAndroid) return 0;

  return sensorOrientation % 360;
}

Then the decoded frame gets rotated before encoding:

final rotationDegrees = _streamFrameRotationDegrees(
  sensorOrientation: sensorOrientation,
);

final outputImage = rotationDegrees == 0
    ? uiImage
    : await _rotateImageClockwise(uiImage, rotationDegrees);

final byteData = await outputImage.toByteData(
  format: ui.ImageByteFormat.png,
);

The rotation helper itself is not complicated, but it is the kind of code where one swapped width/height can ruin your afternoon:

Future<ui.Image> _rotateImageClockwise(
  ui.Image source,
  int degrees,
) async {
  final normalizedDegrees = degrees % 360;
  if (normalizedDegrees == 0) return source;

  final swapsDimensions =
      normalizedDegrees == 90 || normalizedDegrees == 270;
  final outputWidth = swapsDimensions ? source.height : source.width;
  final outputHeight = swapsDimensions ? source.width : source.height;

  final recorder = ui.PictureRecorder();
  final canvas = Canvas(recorder);

  canvas.translate(outputWidth / 2, outputHeight / 2);
  canvas.rotate(normalizedDegrees * math.pi / 180);
  canvas.translate(-source.width / 2, -source.height / 2);
  canvas.drawImage(source, Offset.zero, Paint());

  final picture = recorder.endRecording();
  final rotated = await picture.toImage(outputWidth, outputHeight);
  picture.dispose();

  return rotated;
}

Once that was in place, the saved local images finally looked like what the user saw in the camera preview: head up, neck down, nobody accidentally reclining across the avatar.

A small win, but a very satisfying one.

The temporary debugging tool was worth it

One of the better decisions during this fix was not waiting for the entire upload-display-profile loop every time.

Originally, the feedback cycle was too long:

run face verification
upload images
wait for backend processing
fetch user details again
check the display picture
wonder if the bug was in capture, upload, storage, API, cache, or rendering

That is too many suspects.

So I added a temporary debug-only local preview after capture and before upload. It showed the five local files in a grid labeled center, left, right, up, and down. That made the problem brutally obvious. The images were already rotated before they ever touched remote storage.

That little preview screen did not survive the final cleanup, and it should not have. But as a debugging instrument it was perfect. It shortened the loop from "wait for the full system" to "capture and inspect the exact file."

I keep relearning this lesson: when a pipeline has too many stages, build a peephole into the middle.

Not a permanent feature. Not a grand observability platform. Just a tiny window into the thing you keep making assumptions about.

Why not just use `takePicture()`?

This came up naturally.

The signup selfie flow in another part of the app already uses takePicture(). That path is simpler because the camera plugin handles more of the normal image capture behavior for you. For many apps, that is absolutely what I would prefer.

The liveness flow had a different tradeoff. It wanted the exact frame that passed the rule. If the user smiles and holds still, we capture the stream frame that ML Kit just approved. That avoids a small but real gap between "rule passed" and "photo taken."

So there were two reasonable options:

switch back to takePicture() and lean on the camera plugin's capture behavior
keep stream-frame capture and explicitly own pixel orientation

We chose the second path because it preserved the existing liveness behavior. But choosing it means accepting the responsibility that comes with raw frames. The camera plugin is no longer your orientation babysitter at save time.

That tradeoff is fine, as long as it is intentional.

The device question

After the fix worked, the next question was the right one: will this hold across devices?

The answer is: better than a hardcoded 90-degree rotation, but still worth testing.

Different Android devices may report different camera sensor orientations, commonly 90 or 270. Some devices may even differ between front and back cameras. Using sensorOrientation is the portable part of the fix. It asks the camera what orientation it actually uses instead of assuming every phone is the one on my desk.

But there are caveats.

The current flow assumes portrait capture. If the app allows the user to rotate the phone into landscape during verification, then sensor orientation alone is not enough. We would need to account for current device orientation too.

Also, rotation and mirroring are separate problems. A front camera preview may be mirrored for a familiar selfie experience, but that does not automatically mean the saved image should be mirrored. If logos or text appear reversed, that is a horizontal flip decision, not a rotation fix.

For today's bug, the issue was rotation. The corrected saved PNG now matches the visual expectation.

The thing I am taking away

The interesting part of this bug was not that an image was rotated. That happens all the time in mobile work.

The interesting part was how many layers were technically doing the right thing:

Camera preview looked correct.
ML Kit detection worked because it received rotation metadata.
Upload worked because it uploaded exactly what it was given.
Avatar rendering worked because it displayed exactly what the URL returned.

The bug lived in the one handoff where metadata stopped being enough and pixels became permanent.

That is the kind of issue that makes mobile development feel like plumbing with opinions. Every layer has its own model of reality. Most days they agree. Today they did not.

At least now the user's face is upright.

The Day Search Wasn't Just Search

Fri, 01 May 2026 15:26:17 +0000

Some tasks arrive wearing a tiny hat.

Today’s was: “inspect the vendor search screen.” Simple enough. Search screen, endpoint response, pagination, a couple of screenshots. Nothing too wild.

Then I looked closer and realized the UI was quietly making a promise the backend data did not support.

That is usually where mobile work gets interesting. Not broken in the loud, stack-trace way. Broken in the more slippery way, where the app technically works, but the user walks away with the wrong idea.

The suspicious “Price on request”

The search endpoint was returning vendors with two different service-ish fields:

services
vendorServices

At a glance, both sounded useful. One had pricing information. The other had names like photography, lighting, security, and catering. The UI had been built to show services first, and if that list was empty, fall back to vendorServices with the label “Price on request.”

That fallback looked harmless. It even made the screen feel more complete.

But it was wrong.

The deeper distinction was this:

services represented actual bookable services with prices and service IDs.
vendorServices represented capabilities or declared service categories.

That second list was not enough to create a booking. There was no real pricing model, no service ID, and no guarantee that the item was ready for a client to book. So showing “Price on request” created a nice-looking card while hiding the truth: this vendor had not added bookable services yet.

The old logic was basically:

List<ServiceDisplay> resolveServices(Vendor vendor) {
  final services = vendor.services.map(mapPricedService).toList();

  if (services.isNotEmpty) return services;

  return vendor.vendorServices.map((service) {
    return ServiceDisplay(
      name: service.name,
      priceText: 'Price on request',
    );
  }).toList();
}

The UI was trying to be helpful, but it was flattening two different concepts into one. That is one of those bugs that does not look like a bug until you ask, “Can the user act on this?”

In this case, the answer was no.

So the better version became much more boring, and much more honest:

List<ServiceDisplay> resolveServices(Vendor vendor) {
  final services = vendor.services
      .map(mapPricedService)
      .whereType<ServiceDisplay>()
      .take(2)
      .toList();

  if (services.isNotEmpty) return services;

  return const [];
}

Then the card could render an empty state instead of pretending there was something to book.

Something like:

if (visibleServices.isEmpty) {
  return Text('This vendor has no services yet.');
}

Not glamorous. Very necessary.

The profile screen had to tell the same truth

The search card was only half the story.

The vendor profile screen already had a guard in the booking flow. If a user tapped the book button and there were no services, the app showed an error message. Technically correct, but emotionally clumsy.

From a user’s point of view, the app was saying:

“Book this vendor.”

Then after the tap:

“Actually, no.”

That is not a great contract.

So the bottom CTA had to become state-aware. If the vendor had bookable services, keep the normal booking CTA and the small chat button. If the vendor had no services, remove booking entirely and make chat the primary action.

The important part was not just disabling a button. It was changing the user’s available path:

bool get hasBookableServices => vendor?.services.isNotEmpty == true;

bool get showChatAsPrimaryCta =>
    !isLoading && vendor != null && !hasBookableServices;

That extra loading/vendor check matters. Without it, the screen could briefly think “no services” while the vendor was still loading and show the wrong CTA. Flutter will happily rebuild during every tiny state transition, so the UI has to be careful about what a state actually means.

There is a difference between:

we have loaded the vendor and they have no services
we have not loaded the vendor yet
the request failed and vendor is null

Those states can all look like “empty” if you write the condition too casually.

That was the small detail that made me pause.

Search, suggestions, and the backend contract

The next piece was the search behavior itself.

There was a text field for vendor name search, and there were suggestion chips like “Caterer,” “Event Planner,” “Baker,” and “Rentals.” Originally, tapping a suggestion sent the chip text as the name query parameter.

That worked mechanically, but conceptually it was off.

Those suggestions were not vendor names. They were category or service filters.

The temptation in a mobile app is to “fix” this locally. Filter the current list in Dart, compare strings, hide cards, call it a day. But that would have been the wrong layer. The backend already owned filtering, pagination, and matching logic. The app’s responsibility was just to call the endpoint with the right parameters and render the result.

So suggestion taps became category calls:

static const suggestionCategoryValues = {
  'Caterer': 'CATERER',
  'Sound Engineer': 'SOUND_AND_PA_SYSTEM_PROVIDER',
  'Event Planner': 'EVENT_PLANNER',
  'Rentals': 'RENTALS',
  'Food': 'FOOD_AND_BEVERAGE',
};

Future<void> onSuggestionTapped(String suggestion) async {
  final category = suggestionCategoryValues[suggestion] ?? suggestion;

  searchController.text = suggestion;
  filterCategory = category;

  await fetchVendors(
    name: null,
    category: category,
    page: 1,
  );
}

That little map is not the most exciting code in the world, but it protects the API contract. Display labels can be friendly. Query values can stay backend-shaped.

Mobile apps live in that translation layer more often than we admit.

The filter sheet caught up later

Once suggestions were using category filtering, another inconsistency appeared immediately: the bottom sheet had filters for location and price, but not category.

So category filtering existed only through suggestions. That meant users could discover it by accident, but not intentionally. Not great.

The filter sheet needed a category dropdown that did the same thing: send a category query to the backend.

The interesting decision here was what values to show and what values to send. I wanted the UI to say “Food and Beverage,” not FOOD_AND_BEVERAGE. But the API still needed the enum-style value.

So the dropdown carried backend values internally and used a display mapper for labels:

static const categoryOptions = [
  'FOOD_AND_BEVERAGE',
  'EVENT_PLANNER',
  'PHOTOGRAPHER',
  'RENTALS',
];

static const categoryLabels = {
  'FOOD_AND_BEVERAGE': 'Food and Beverage',
  'EVENT_PLANNER': 'Event Planner',
  'PHOTOGRAPHER': 'Photographer',
  'RENTALS': 'Rentals',
};

String formatCategory(String value) {
  return categoryLabels[value] ?? value.replaceAll('_', ' ');
}

This is one of those places where clean architecture is not a diagram. It is a tiny choice about which string crosses a boundary.

The app can be warm and readable. The network request can be strict and boring. Everyone wins.

The sneaky problem with clearing results

After the category dropdown went in, another UX issue showed up.

Text search had a clear button inside the search field. If I typed a vendor name, I could tap the suffix X and reset the search.

But filters from the bottom sheet did not always put visible text in the search field. So after filtering by category, location, or price, the user could see “Result(s) Found” but had no obvious way to get back to the unfiltered list.

This is the kind of detail that is easy to miss when testing happy paths. The data was correct. The request was correct. Pagination still worked. But the screen had trapped the user in a filtered state unless they reopened the sheet and manually changed things.

So I added a small clear action beside the results count.

Not a giant reset panel. Not another modal. Just an X next to:

12 Result(s) Found

That X clears:

name search
category
location
price range
suggestion state

Then it reloads page one from the backend with no filters.

The method is intentionally blunt:

Future<void> clearSearchAndFilters() async {
  searchController.clear();

  filterLocation = null;
  filterMinPrice = null;
  filterMaxPrice = null;
  filterCategory = null;
  categorySearchText = null;

  await fetchVendors(
    name: null,
    category: null,
    location: null,
    minPrice: null,
    maxPrice: null,
    page: 1,
  );
}

Sometimes the cleanest UX state reset is not clever. It is just complete.

The thing I kept coming back to

The technical work today was not hard because of algorithms. It was hard because the screen had several overlapping meanings:

A search query can be a vendor name.
A suggestion looks like text but behaves like a category filter.
A vendor can have declared capabilities but no bookable services.
A profile can be valid but not bookable.
Empty data can mean “not loaded yet” or “loaded and truly empty.”

The main lesson was that UI should not invent certainty the data does not provide.

If there are no bookable services, say that.

If the backend owns filtering, call the backend.

If a filter can be applied, give the user a way to clear it.

Tiny decisions. Big difference.

By the end, the screen felt less magical and more honest. That is usually a good trade.

Building a Zomato-Like Multi-City Food Delivery App with Flutter & Firebase

Tue, 28 Apr 2026 05:29:56 +0000

Hey everyone, Surendra Kumar here —Flutter/Firebase developer from Banda, India. I've been building production apps under Gfood Delivery Private Limited, and today I want to share the architecture behind my most ambitious project yet: Zesto, a multi-city food delivery platform built entirely with Flutter and Firebase.
Zesto isn't a tutorial project. It's a real, working platform — 4 Flutter apps, a complete Firebase backend, and architecture decisions modeled after how production platforms like Zomato actually work.
Want to try it before reading? Download the customer app APK and test it yourself:
Download Zesto Customer App https://github.com/ssurekumar01111-hue/zesto-demo/releases/download/v1.0-beta/app-release.apk
I'd love your feedback and improvement ideas after reading.

The 4-App Ecosystem
Zesto consists of four interconnected Flutter applications:

Customer App — Multi-city restaurant discovery, cart, Razorpay + wallet payments, live GPS tracking, reviews
Restaurant Partner App — Order management, menu CRUD, earnings dashboard, FCM order alerts
Driver App — Order accept/reject, live delivery tracking, earnings, payout requests
Flutter Web Admin Panel — 14 screens covering cities, zones, restaurants, drivers, orders, analytics, reviews, ads, config, and audit logs

The Core Architecture Decision: City + Zone Scoping
This is the most important architectural decision in Zesto — and the one that separates it from basic food delivery tutorials.
Every single Firestore document has two fields:
dart{
"city_id": "banda_up",
"zone_id": "banda_zone_1",
// ... rest of document
}
Every query filters by city_id first:
dartFirebaseFirestore.instance
.collection('restaurants')
.where('city_id', isEqualTo: currentCityId)
.where('is_active', isEqualTo: true)
.snapshots();
Why does this matter? Without city scoping, as you add cities your queries return restaurants from everywhere. Firestore has no built-in geographic filtering — you have to design it in from day one. Retrofitting this later would require rewriting every query and migrating every document.
Zones sit inside cities and control driver assignment. When an order is placed, the Cloud Function assigns it to available drivers in the same zone first, then expands to the full city if no zone drivers are available.

Firebase Custom Claims for RBAC
Zesto has 5 user roles: customer, restaurant_owner, driver, admin, super_admin. Managing this with Firestore documents alone creates security holes — a user could theoretically write to their own document and escalate their role.
The solution is Firebase custom claims set via Cloud Functions:
javascript// functions/src/admin/setUserRole.js
exports.setUserRole = functions.https.onCall(async (data, context) => {
if (!context.auth.token.super_admin) {

throw new functions.https.HttpsError('permission-denied', 'Not authorized');

}
await admin.auth().setCustomUserClaims(data.uid, {

role: data.role,
city_id: data.cityId,

});
});
On the Flutter side, the role is read from the ID token directly:
dartfinal token = await FirebaseAuth.instance.currentUser?.getIdTokenResult();
final role = token?.claims?['role'] as String?;
This means even if someone modifies their Firestore document, the custom claim on the token is what gates access. Firestore rules enforce this:
javascript// firestore.rules
match /orders/{orderId} {
allow read: if request.auth.token.role == 'admin'

|| request.auth.token.role == 'restaurant_owner'
|| request.auth.uid == resource.data.customer_id;

}

MobX for State Management
Zesto uses MobX across all 4 apps. Here's why I chose it over Riverpod or GetX for this project:
MobX's reactive observables map perfectly to Firestore streams. When a Firestore stream emits a new value, MobX automatically rebuilds only the widgets that consume that observable — no manual setState, no context.watch boilerplate.
dart// core/stores/order_store.dart
class OrderStore = OrderStore with $OrderStore;

abstract class _OrderStore with Store {
@observable
ObservableList activeOrders = ObservableList();

@observable
OrderStatus currentStatus = OrderStatus.placed;

@action
void updateOrderStatus(String orderId, OrderStatus status) {

final idx = activeOrders.indexWhere((o) => o.id == orderId);
if (idx != -1) {
  activeOrders[idx] = activeOrders[idx].copyWith(status: status);
}
currentStatus = status;

}
}
The store subscribes to a Firestore stream once and updates observables. Every widget that reads activeOrders rebuilds automatically. Clean, testable, no rebuild storms.

Dual Payment Path: Razorpay + In-App Wallet
Zesto supports two payment methods and they interact with each other in interesting ways.
Razorpay handles card/UPI payments. The flow is standard — create an order via Cloud Functions, open Razorpay checkout, handle the webhook callback.
The wallet is more interesting. Each customer has a wallet_balance field on their user document. When they pay via wallet:
javascript// functions/src/payments/walletPayment.js
exports.processWalletPayment = functions.https.onCall(async (data, context) => {
const uid = context.auth.uid;

return admin.firestore().runTransaction(async (transaction) => {

const userRef = admin.firestore().collection('users').doc(uid);
const userDoc = await transaction.get(userRef);

const currentBalance = userDoc.data().wallet_balance;
if (currentBalance < data.amount) {
  throw new functions.https.HttpsError('failed-precondition', 'Insufficient balance');
}

transaction.update(userRef, {
  wallet_balance: admin.firestore.FieldValue.increment(-data.amount)
});

transaction.set(admin.firestore().collection('wallet_txns').doc(), {
  uid,
  amount: -data.amount,
  type: 'debit',
  order_id: data.orderId,
  created_at: admin.firestore.FieldValue.serverTimestamp(),
});

});
});
The Firestore transaction ensures the balance check and deduction happen atomically — no race condition where two simultaneous orders drain the wallet below zero.

Cloud Functions: Domain-Split Architecture
Instead of one massive index.js, Zesto's Cloud Functions are split by domain:
functions/src/
├── orders/
│ ├── placeOrder.js # Create order, notify restaurant
│ ├── assignDriver.js # Zone-based driver assignment
│ └── onOrderDelivered.js # Earnings calculation, wallet credit
├── payments/
│ ├── razorpayWebhook.js # Payment confirmation
│ └── walletPayment.js # Wallet debit/credit
└── admin/

├── approveRestaurant.js
└── setUserRole.js

Each function is independently deployable. When I fix a bug in assignDriver.js, I deploy only that function — not the entire backend.

The Driver Assignment Problem
When an order is placed, the platform needs to assign a driver. Here's the simplified logic:
javascriptexports.assignDriver = functions.firestore
.document('orders/{orderId}')
.onCreate(async (snap, context) => {

const order = snap.data();

// 1. Find online drivers in the same zone
const driversSnap = await admin.firestore()
  .collection('drivers')
  .where('city_id', isEqualTo: order.city_id)
  .where('zone_id', isEqualTo: order.zone_id)
  .where('is_online', isEqualTo: true)
  .where('current_order_id', isEqualTo: null)
  .limit(5)
  .get();

if (driversSnap.empty) {
  // Expand to full city
  // ... same query without zone_id filter
}

// 2. Send FCM notification to available drivers
// First driver to accept wins (handled by transaction in Driver app)
const tokens = driversSnap.docs.map(d => d.data().fcm_token);
await admin.messaging().sendMulticast({
  tokens,
  data: { type: 'NEW_ORDER', order_id: context.params.orderId }
});

});
On the driver side, accepting an order uses a Firestore transaction with three guards to prevent race conditions — only one driver can claim the order even if multiple tap Accept simultaneously.

What's Coming
Zesto is launching soon on Gumroad and Codester as commercial source code — complete, ready-to-customize. It includes all 4 Flutter apps, the complete Cloud Functions backend, Firestore security rules, and developer documentation.
Try the customer app right now:
https://github.com/ssurekumar01111-hue/zesto-demo/releases/download/v1.0-beta/app-release.apk
I'd genuinely love your feedback — what works well, what feels off, what you'd build differently. Drop a comment or reach me at Emails are not allowed.

Surendra Kumar — Flutter/Firebase developer, Banda, India
Portfolio: portfolio.gfood.in | GitHub: ssurekumar01111-hue

How I Built a Complete On-Demand Home Services App (ServeNow) with Flutter & Firebase

Tue, 28 Apr 2026 04:39:08 +0000

Hey everyone, Surendra Kumar here, a self-taught Flutter developer from Banda, India. I've spent a good chunk of my time building and shipping production apps, like those I worked on for Gfood Delivery Private Limited. Today, I want to share the story behind one of my most ambitious projects: ServeNow.

As an indie developer, I've always been driven to build real solutions—apps that don't just look pretty in a tutorial but actually work robustly in the wild. That's exactly the philosophy I brought to ServeNow.

What is ServeNow? Crafting a Full-Fledged Marketplace

ServeNow isn't just another demo app. It's a complete, production-ready on-demand home services marketplace built from the ground up with Flutter and Firebase. My goal was to create a comprehensive system that could handle everything from booking a beautician to fixing a leaky faucet, all while providing a smooth experience for customers, service providers, and administrators.

To achieve this, I engineered ServeNow as a suite of four interconnected applications, each designed for a specific user role:

Customer App: This is where users come to life. They can browse various services (beauty, cleaning, plumbing, electrical, etc.), book appointments, track their service provider in real-time, chat with them, make secure payments via Razorpay, and leave reviews.
Provider App: For the businesses offering services. They can accept new bookings, manage their schedule and service offerings, track their real-time earnings, and request payouts.
Handyman App: This is for the actual service professionals. It's a multi-service pro app featuring a broadcast job matching system, allowing handymen to pick up nearby jobs. It also includes an onboarding and approval flow for new pros.
Flutter Web Admin Panel: The control center. This robust web panel gives administrators full control over users, bookings, categories, service providers, payout requests, and provides crucial analytics to keep the marketplace running efficiently.

Why Flutter & Firebase? My Tech Stack Decisions

When embarking on ServeNow, the choice of technology was critical. I needed a stack that offered rapid development, scalability, real-time capabilities, and robust performance without requiring a massive infrastructure investment.

Flutter (Dart) for the Frontend

Flutter was a no-brainer for the mobile applications and the web admin panel.

Single Codebase: Building four distinct applications (Customer, Provider, Handyman, and Admin Panel) from a single Flutter codebase drastically cut down development time and ensured UI/UX consistency across platforms.
Performance: Flutter's native compilation and widget-based architecture deliver smooth, high-performance applications that feel truly native.
Developer Experience: Hot Reload and a rich widget catalog accelerated my development cycles, allowing for quick iterations and bug fixes.

Firebase for the Backend (My Go-To for Indie Development)

Firebase has been my backend of choice for many projects, and ServeNow was no exception. It offered the complete suite of tools I needed.

Firestore: This is the heart of ServeNow's data. I chose Firestore for its real-time capabilities, strong querying, and scalability.
- Architecture Decision: I structured collections like users, services, providers, handymen, bookings, and chats. For bookings, I leaned into denormalization by embedding critical but static details (like customer name, service price) directly within the bookings document. This minimizes expensive cross-collection reads for common operations and ensures faster data retrieval, especially for lists of bookings. Subcollections were used for highly related, nested data, like messages within a chat document.
Firebase Authentication: For secure and easy user management across all apps, supporting email/password and potentially Google Sign-In for future expansion.
Cloud Functions (JavaScript): This was indispensable for server-side logic without managing actual servers.
- Architecture Decision: Cloud Functions handle critical backend tasks:
  - Razorpay Webhooks: Securely processing payment callbacks and updating booking statuses post-payment.
  - FCM Triggers: Sending real-time push notifications for booking updates, new job broadcasts (to handymen), and chat messages.
  - Data Aggregation: Calculating real-time earnings for providers and handymen, and managing payout requests.
  - Background Tasks: Handling approval flows for new handymen and providers.
Firebase Storage: For storing user profile pictures, service images, and any other media files securely.
Firebase Cloud Messaging (FCM): Essential for real-time communication between the apps – from notifying handymen about new jobs in their area to letting customers know their service provider is on the way.

Other Key Technologies:

Razorpay: Integrated as the primary payment gateway, crucial for handling transactions securely within the Indian market. Cloud Functions were vital here for handling payment success/failure callbacks.
rxdart: I leveraged rxdart for reactive programming, especially for managing complex streams of data and state within the apps, ensuring a smooth and responsive user experience.
Google Maps: Integrated for live tracking of handymen, defining service areas, and visualizing job locations.

Architectural Decisions & Overcoming Challenges

Building ServeNow meant tackling typical marketplace complexities.

Real-time Synchronization: A core requirement. Firestore's real-time listeners were used extensively. For example, when a handyman accepts a job, the customer's app updates instantly, and the provider's app reflects the booking status change. This required careful management of data updates and notification triggers via Cloud Functions.
Scalability: Thinking beyond just a few users. Firestore's inherent scalability and Cloud Functions' serverless architecture meant the platform could grow without significant re-engineering of the backend.
Job Broadcasting & Matching: This was an interesting challenge for the Handyman app. When a new service request comes in, I use Firestore queries based on service type and location, combined with FCM, to broadcast the job to eligible handymen. The first to accept gets the job, with race conditions handled by Firestore transactions in Cloud Functions.
Secure Payouts: The provider and handyman apps needed a robust payout request system. This involves tracking earnings in Firestore, initiating payout requests, and then an admin manually (or via a future integration) processing these, all managed through the Admin Panel and Cloud Functions.
Developer Documentation: Knowing that this was a complex system, I invested significant time in creating a comprehensive 16-page developer documentation (v2.0). It covers everything from project setup to API details, making it easy for anyone to get started.

The Indie Developer Ethos: Production-Grade from Day One

What makes ServeNow different is that it's built with a "production-grade" mindset. This isn't a collection of loosely connected tutorials; it's a fully integrated, tested system designed to be deployed and used in a real business environment. Every feature, every line of code, was written with stability, scalability, and maintainability in mind. It comes complete with signed APKs and a thorough setup guide, so you can literally launch it.

Building ServeNow was a journey of applying everything I've learned about Flutter, Firebase, and shipping real products. It's proof that with dedication and the right tools, indie developers can build incredibly powerful, complete solutions.

Ready to Launch Your Own Home Services Marketplace?

If you're looking for a robust, ready-to-launch foundation for an on-demand home services marketplace, ServeNow is designed to be exactly that. It handles the complexities, so you can focus on your business.

You can learn more about my work and projects like ServeNow by checking out my GitHub profile or reaching out via email.

My GitHub Profile: ssurekumar01111-hue
Email: ssure.kumar01111@gmail.com
https://morningstar47jb.gumroad.com/l/viqos

Thanks for reading! I hope this deep dive into ServeNow gives you some insights into building complex applications as an indie developer.

Building a Resilient Real-Time WebSocket Stream in Flutter (RxDart + Clean Architecture + BLoC)

Mon, 27 Apr 2026 05:30:51 +0000

Most tutorials show how to connect to a WebSocket.

Very few show what happens when:

The network drops
DNS fails
The server stops sending data
The stream silently hangs

This article focuses on handling those cases properly.

The Problem

A basic WebSocket implementation:

final channel = WebSocketChannel.connect(uri);
channel.stream.listen(...);

Works… until real-world conditions appear:

Network loss → no error  
Stream freezes silently  
App never reconnects  
Users see stale data

The Goal

We want a stream that:

reconnects automatically
handles both errors and silent failures
retries with exponential backoff
does not crash the app
integrates cleanly with BLoC

Step 1: Deferred Connection (Rx.defer)

Instead of creating the connection immediately, we defer it:

return Rx.defer(() async* {
  final channel = _websocketService.connect();
  await channel. ready;
  yield* channel.stream;
});

This ensures that each retry creates a fresh connection.

Step 2: Handle Connection Errors

If the connection fails:

try {
  final channel = _websocketService.connect();
} catch (e) {
  yield* Stream.error(e);
}

Convert failures into stream errors so retry logic can handle them.

Step 3: Handle Silent Failures (Timeout)

WebSockets may stop emitting without throwing errors.

.timeout(
  const Duration(seconds: 5),
  onTimeout: (sink) {
    sink.addError("Timeout");
  },
)

This forces a retry when no data is received.

Step 4: Control Update Frequency

Real-time streams can overwhelm the UI.

.sampleTime(const Duration(seconds: 1))

This emits the latest value at a fixed interval.

Step 5: Retry Logic (RetryWhenStream)

RetryWhenStream(
  streamFactory,
  (error, _) {
    final delay = Duration(seconds: (1 << attempt).clamp(1, 60));
    attempt++;
    return Rx.timer(null, delay);
  },
);

This implements exponential backoff:

Retry after 1s → 2s → 4s → 8s → ...

Final Remote Data Source

Stream<AllMidsModel> connectToStream() {
  var attempt = 0;

  return RetryWhenStream(
    () {
      return Rx.defer(() async* {
        try {
          final channel = _websocketService.connect();
          await channel.ready;

          yield* channel.stream
              .map((event) {
                final json = jsonDecode(event as String);

                if (json['channel'] == 'allMids') {
                  return AllMidsModel.fromJson(json['data']);
                }
                return null;
              })
              .whereType<AllMidsModel>()
              .timeout(
                const Duration(seconds: 5),
                onTimeout: (sink) => sink.addError("Timeout"),
              )
              .sampleTime(const Duration(seconds: 1))
              .doOnData((_) => attempt = 0);
        } catch (e) {
          yield* Stream.error(e);
        }
      });
    },
    (error, _) {
      final delay = Duration(seconds: (1 << attempt).clamp(1, 60));
      attempt++;
      return Rx.timer(null, delay);
    },
  );
}

Clean Architecture Integration

Data Layer

Handles WebSocket connection, retry logic, and parsing. Returns a stream of models.

Domain Layer

abstract interface class PriceRepository {
  Either<Failure, Stream<AllMids>> subscribe();
}

Responsible for:

mapping models to entities
converting exceptions into failures

Use Case

class SubscribeToStream implements StreamUseCase<AllMids, NoParams> {
  final PriceRepository repo;

  @override
  call(_) => repo.subscribe();
}

Presentation Layer (BLoC)

Instead of passing streams to the UI, BLoC consumes the stream:

on<SubscribeToPriceStream>(
  _onSubscribe,
  transformer: restartable(),
);

await emit.forEach(
  stream,
  onData: (data) => PriceUpdated(data),
  onError: (e, _) => PriceStreamError(e.toString()),
);

Why `restartable()`?

It ensures:

new events cancel previous subscriptions
No duplicate streams remain active

UI Layer

switch (state) {
  case PriceUpdated(:final data):
    return Text("${data.price}");

  case PriceStreamError(:final msg):
    return Text(msg);

  case StartingPriceStream():
    return CircularProgressIndicator();
}

The UI reacts to states only. It has no knowledge of streams.

What This Solves

automatic reconnection
silent failure handling
controlled UI updates
crash prevention
clean separation of concerns

Key Takeaways

WebSockets do not always fail with errors
You must handle both errors and inactivity
Retry logic must recreate the connection
Streams should be owned by BLoC, not UI
RxDart is powerful when used with intent

Final Thought

Real-time systems are not about receiving data.

They are about handling failure conditions reliably, so users never notice them.

The Tiny Red Dot That Wasn't Tiny

Tue, 21 Apr 2026 13:17:28 +0000

Today’s task looked harmless from the outside: show unread notifications, let users mark them as seen, and put a red dot on the bell icon when there is something new.

Classic mobile app stuff. Nothing dramatic. Just a bell, a list, a few cards, and one dot.

Naturally, it was not that simple.

The funny thing about notification work is that it lives in the uncomfortable space between backend truth and frontend immediacy. The backend knows what is actually unread. The UI knows what the user just tapped. Push notifications know something happened. Sockets know something happened too, sometimes faster. And snackbars are off on the side saying, “Hey, should I also be involved?”

By midday, the red dot was no longer a red dot. It was a state synchronization problem wearing a very small costume.

The backend changed its mind, which was actually helpful

The first shape of the notification payload was fairly raw. Every notification had a type, a timestamp, a read flag, and optional metadata. Some metadata had a bookingId, messages had sender/message IDs, and a few account-related notifications had no metadata at all.

Then the backend evolved in a useful direction: every notification metadata payload started carrying a summary field.

That changed the UI strategy quite a bit.

Instead of the app inventing every notification message from scratch, the backend could provide the user-facing summary while Flutter handled presentation: title, tone, icon/avatar, time label, action hints, and where the tap should eventually go.

That felt like the right division of responsibility.

The server knows the event context. The app knows how to make it feel native.

So the mapper became less of a sentence factory and more of a translation layer:

class NotificationUiItem {
  final String id;
  final String type;
  final String title;
  final String summary;
  final DateTime createdAt;
  final bool read;
  final String? bookingId;
  final String? serviceId;
  final String? senderId;
  final String? messageId;
  final String? photo;
  final NotificationUiTone tone;

  const NotificationUiItem({
    required this.id,
    required this.type,
    required this.title,
    required this.summary,
    required this.createdAt,
    required this.read,
    required this.tone,
    this.bookingId,
    this.serviceId,
    this.senderId,
    this.messageId,
    this.photo,
  });
}

Nothing wild there, but it gave the UI a stable language. Client notifications and vendor notifications could both consume the same backend response without pretending they were separate worlds.

That was one of the nicer parts of the day: deleting mental duplication before it had time to harden.

The trap: “just fetch when something happens”

At some point I had to decide how the red dot should react to realtime events.

The obvious approach is tempting:

Socket event comes in, call GET https://api.example.com/notifications, update the unread state.

It sounds clean because the backend remains the single source of truth. But it also means every realtime event can become a network call. Booking accepted? Fetch. Client paid? Fetch. Vendor account approved? Fetch. Push received while the app is open? Fetch again.

That starts to feel a little too eager.

The red dot does not need the full notification list. It only needs to know whether there is probably something unread.

So I split the behavior into two layers:

Realtime events are allowed to set hasUnread to true immediately.
The actual notifications endpoint is fetched when the user opens or refreshes the notifications screen.
Tapping or clearing notifications updates the badge optimistically.
A successful refresh becomes the source of truth again.

The controller ended up intentionally small:

class UnreadNotificationsController {
  final ValueNotifier<bool> hasUnread = ValueNotifier<bool>(false);

  Future<void> refreshFromBackend() async {
    final result = await getUnreadNotifications();

    result.fold(
      (_) {
        // Keep the current local state if refresh fails.
      },
      (response) {
        hasUnread.value = response.notifications.isNotEmpty;
      },
    );
  }

  void notifyNewUnread() {
    hasUnread.value = true;
  }

  void markAllSeenLocally() {
    hasUnread.value = false;
  }
}

The small detail I care about there: failed refresh does not force the dot off.

That is the kind of bug that feels tiny until a user sees it. Imagine a socket event turns the dot on, then a shaky network request fails, and suddenly the app says there are no notifications. That is not truth. That is the UI being overconfident.

So failure preserves the last known state.

Optimistic UI, but not reckless UI

The notification cards needed two actions: tap one notification as seen, and clear all notifications.

Both should feel immediate. Nobody wants to tap a notification and wait for a spinner before the card visually calms down.

So the screen fades a card instantly when tapped, calls the mark-as-seen endpoint in the background, and restores state only if the request fails.

Same with clear-all: empty the list immediately, turn off the badge, then restore if the backend refuses.

That pattern is simple on paper, but it gets tricky around shared state. The screen has local state like:

final Set<String> seenNotificationIds = {};

The badge has global-ish app state:

final ValueNotifier<bool> hasUnread;

Those two need to agree without becoming the same thing.

Local card fading is about presentation. The badge is about app-level unread status. If one notification is tapped but others remain unread, the card should fade but the bell should stay red. If the last visible unread notification is tapped, the bell can turn off optimistically.

That distinction saved the implementation from becoming mushy.

Messages were the one awkward guest

Messages complicated the decision a bit.

The app already has message socket events and snackbars. A new chat message can appear while the user is in another tab, and the app may show a snackbar preview. The backend may also create a notification for that message. But once the user reads the chat, the backend can mark that message notification as read on the next fetch.

So should message events turn on the notification bell dot?

I chose not to, at least for now.

Not because messages are unimportant. Actually, the opposite: messages often deserve their own unread behavior. If the chat tab already has message-specific state, using the general notification bell for every message can make the app feel noisy.

So the controller ignores message-style push events and lets the backend refresh settle it later:

void handlePushPayload(PushPayload payload) {
  final eventType = payload.eventType.trim();

  if (payload.isMessageEvent || eventType == 'NEW_MESSAGE') return;
  if (eventType.isEmpty) return;

  notifyNewUnread();
}

This means booking, payment, account, document, and status notifications can light the bell immediately. Messages can still appear in the notifications list if the backend returns them, but they do not drive the red dot in realtime.

That might change later. And if it does, the change is thankfully tiny: remove that guard and subscribe to message socket events too.

I like when a decision is reversible without surgery.

The part that felt architectural

The more interesting thought came after the unread state was working: what should happen when a user taps a notification card?

Push notifications already navigate somewhere. Usually not super deep, but enough to open the right section of the app. For example, a booking event might open the bookings tab. A message might open the messages tab. A payout-related notification might open the payout screen.

The in-app notification cards should not invent a second routing brain.

The cleaner direction is to create a shared notification navigation resolver. Push payloads and backend notification cards can both be converted into the same internal input:

class NotificationRouteInput {
  final String type;
  final String? bookingId;
  final String? serviceId;
  final String? senderId;
  final String? messageId;
  final String? vendorId;

  const NotificationRouteInput({
    required this.type,
    this.bookingId,
    this.serviceId,
    this.senderId,
    this.messageId,
    this.vendorId,
  });
}

Then the resolver decides:

message notification: messages tab, or exact chat if enough data exists
booking notification: bookings tab, ideally with the exact booking opened
document notification: payout or document area
account rejected/suspended: support or account status screen
vendor application: admin approval flow, if the app has one

The important thing is consistency. If a push notification and an in-app notification represent the same event, they should not send the user to different places because two separate pieces of code drifted apart.

That is the kind of duplication that does not hurt today, then quietly taxes every future feature.

What I’d keep from today

The biggest lesson was not about ValueNotifier, sockets, or endpoints. It was about being careful with what kind of truth each part of the app owns.

The backend owns durable unread state.

Sockets and push own immediacy.

Notification screens own presentation and local optimistic feedback.

The badge owns one tiny app-level question: “Should I show a dot?”

Once those boundaries were clear, the implementation stopped feeling like a pile of callbacks and started feeling like a small system.

Still a slightly annoying system. Notifications always are. They are where product expectations, backend timing, OS behavior, and user attention all meet in a narrow hallway.

But today’s version is better than the naive one I almost built.

No overfetching on every event. No forcing the dot off on refresh failure. No duplicated client/vendor notification models. No pretending message notifications are the same as booking/payment/account events when the app already treats chat specially.

All of that for a red dot.

A very small red dot.

The Message That Was There, But Not There

Tue, 21 Apr 2026 13:16:42 +0000

Today I worked on one of those bugs that sounds suspiciously simple when someone describes it.

"When a new message comes in, the message screen updates. But when I open the chat, the message is not there. If I go back, refresh, and open it again, then it shows."

That sentence has all the ingredients of a quiet afternoon turning into a long stare at state management.

The app has a fairly normal chat flow. There is a messages screen with conversation previews, unread counts, recent chats, and the latest message text. Then there is a chat screen that shows the actual thread. Messages arrive through a socket. Push or foreground notifications can also show a snackbar. The backend stores read status, and the app marks messages as read once the user opens the chat.

Nothing exotic. Which, of course, is exactly why it was interesting.

The preview was telling the truth

The first clue was that the message list did update.

When a message arrived, the preview changed. The unread count changed. The notification snackbar appeared. So this was not a socket connection issue, not a missing event, and not a routing issue.

The list knew about the new message.

But the chat screen did not.

That narrowed the shape of the bug quite a bit. Somewhere between "socket event reached the messages screen" and "chat screen opened", the data was getting thinner.

The messages screen had a ChatPreview model. It carried the things you expect:

class ChatPreview {
  final String latestMessage;
  final int unreadCount;
  final String userId;
  final String? conversationId;
  final List<ChatMessage> initialMessages;

  // ...
}

That last field was the important one: initialMessages.

The chat screen was not always fetching a fresh thread immediately when opened. It was initialized from the preview object:

_messages = widget.initialMessages ?? [];

So the list screen was not just a list screen. It was also acting as a lightweight cache for the first render of the chat screen.

That is a reasonable design. It makes the chat open quickly. It avoids a blank screen while waiting for the network. It also means the cache has to be correct.

And mine was not.

The tiny split-brain

The socket handler on the messages screen was doing something like this:

existing.copyWith(
  latestMessage: latestMessage,
  time: timestamp,
  unreadCount: existing.unreadCount + 1,
);

That made the preview look right.

But it did not add the new socket message to initialMessages.

So the user saw the new message in the list, tapped the conversation, and the chat screen opened with the old cached message list. The newest message was effectively living in the preview text, but not in the actual message collection.

That explains the weird part where the message appeared only after a manual refresh. The refresh pulled the full conversation again from the backend, rebuilt initialMessages, and finally the chat screen had the missing message.

It also explained the unread count behaving oddly. Opening the chat locally cleared the unread count in the list UI, but the chat screen could not mark that new message as read because the message was not in _messages. After refresh, the backend still considered it unread. That was not the backend being stubborn. It was the UI never giving the read-marking code the message id it needed.

This is the kind of bug where every individual piece is doing something understandable, but the system as a whole lies to you.

The fix was not to refresh harder

The tempting fix would have been: "Just fetch the whole conversation every time the chat opens."

That would probably work. It would also make the app feel a little heavier, especially in a realtime chat where the socket already handed us the message. Pulling from the backend after receiving the exact event felt like paying twice for the same information.

The better fix was to make the socket path update both layers of state:

the visible preview fields
the cached initialMessages passed into the chat screen

So when a socket message arrives, I now build a real ChatMessage from the socket payload:

final incomingMessage = ChatMessage(
  id: messageId,
  message: content,
  timestamp: timestamp,
  isSender: senderId == currentUserId,
  messageType: resolvedMessageType,
  attachmentIds: attachmentIds,
  tempId: tempId,
  status: status,
);

Then I merge it into the preview's cached messages:

List<ChatMessage> mergeMessageIntoCache(
  List<ChatMessage> currentMessages,
  ChatMessage incomingMessage,
) {
  final nextMessages = List<ChatMessage>.from(currentMessages);

  final existingIndex = nextMessages.indexWhere(
    (message) =>
        message.id == incomingMessage.id ||
        (incomingMessage.tempId != null &&
            message.tempId == incomingMessage.tempId),
  );

  if (existingIndex == -1) {
    nextMessages.add(incomingMessage);
  } else {
    nextMessages[existingIndex] = incomingMessage;
  }

  nextMessages.sort((a, b) => a.timestamp.compareTo(b.timestamp));
  return nextMessages;
}

The tempId part matters because optimistic UI is usually lurking somewhere nearby in chat apps. A sent message may appear locally before the server returns its final id. If the server later echoes it back, you do not want a duplicate bubble. Matching by id and tempId keeps that handoff cleaner.

Now the preview update includes the actual message cache:

existing.copyWith(
  latestMessage: latestMessage,
  time: timestamp,
  unreadCount: shouldIncrement ? existing.unreadCount + 1 : 0,
  initialMessages: mergeMessageIntoCache(
    existing.initialMessages,
    incomingMessage,
  ),
);

The result is less dramatic than the bug: the user taps the chat, the message is already there, and the read logic can do its job.

Lovely when software becomes boring again.

Then attachments joined the conversation

After that, another small issue showed up.

Text messages were fine, but when a new image or voice note arrived, the live preview said:

Attachment

After a manual refresh, it correctly said:

Image

or:

Voice note

Same screen. Same message. Different label depending on whether it came from the socket path or the refresh path.

That pointed to another mismatch.

The refresh path had more context. It could inspect or infer attachment metadata and resolve the message type properly. The socket path was mostly trusting the raw type field from the event. If the type was missing, generic, lowercase, or not specific enough, the UI fell back to Attachment.

This is one of those details that is easy to miss because the fallback is not broken. "Attachment" is technically acceptable. It just feels unfinished, especially when the same message becomes "Image" after refresh.

So the socket preview path needed to use the same resolver as the loaded conversation path:

final attachmentIds = extractAttachmentIds(messageData);

final resolvedMessageType =
    attachmentIds.isNotEmpty
        ? await resolveMessageType(rawType, attachmentIds)
        : mapMessageType(rawType.toUpperCase());

final latestMessage =
    content.isNotEmpty
        ? content
        : labelForMessageType(resolvedMessageType);

That made the live preview and refreshed preview agree.

The important thing here is not the label. It is the consistency of the data pipeline. If one path says "Image" and another says "Attachment", users may not describe it as a data pipeline issue. They will just say, very fairly, "This screen is weird."

Client and vendor were the same bug twice

This app has both client and vendor versions of the messages screen. They are not identical screens in the product sense, but their chat-preview logic is similar enough that fixing only one side would have been lazy.

So the same cache merge and attachment preview fix went into both message screens.

This is where duplicated UI logic starts tapping you on the shoulder.

Duplication is not automatically evil. Sometimes two flows really do need room to evolve separately. But realtime chat logic is the kind of thing that gets expensive when copied around. Socket payload parsing, attachment normalization, message deduping, unread count handling, and read-status behavior are all easy to get almost-right in two places.

Almost-right is where bugs breed.

I did not do the larger refactor today, but the shape is obvious: this logic wants to live somewhere shared. Not necessarily a giant abstraction. Maybe just a small mapper/helper that turns socket payloads into ChatMessage and preview metadata. Enough to stop the client and vendor screens from drifting apart.

There is a difference between noticing a refactor and doing it immediately. Today the right move was to fix the bug tightly, verify both screens, and leave the larger cleanup as a clear next step.

The part I keep thinking about

The bug was not caused by Flutter being strange. It was caused by state having two representations:

preview state
detail state

The preview state changed first, so the UI looked alive. But the detail state stayed stale, so the next screen felt broken.

That is a very mobile-app kind of bug.

Mobile interfaces often optimize for immediacy. We cache, prefill, optimistic-update, debounce, hydrate, and subscribe to streams. All of that is normal. But once there are multiple ways for the same entity to enter the UI, each path has to preserve the same meaning.

A message cannot only be a string in one path and a full object in another.

An attachment cannot be "whatever the raw event said" in one path and "resolved from metadata" in another.

Unread state cannot be cleared visually if the message id never reaches the code that persists the read receipt.

None of these are huge architectural revelations. They are smaller than that, and maybe more useful because of it.

Today's reminder: realtime UI bugs are often not about receiving data. They are about receiving data into the wrong layer of state.

And yes, sometimes the message is there.

Just not where the next screen is looking.

Flutter’s Execution Model — Explained Like a Human

Tue, 14 Apr 2026 08:50:35 +0000

If you’ve been building with Flutter for a while, you’ve definitely heard terms like AOT and JIT thrown around.

Maybe you know debug is slower than release.
Maybe you’ve wondered what actually ends up inside your APK.

But like… what’s really going on under the hood?

Let’s open it up properly — no buzzwords, no hand-wavy stuff. Just what actually happens to your code, when it happens, and why Flutter lowkey has a massive edge.

The Simplest Way to Think About It

Imagine you invited someone over for dinner.

AOT (Ahead of Time) is you cooking everything beforehand.
Full meal ready. Table set. Chef mode ON.

They walk in → boom, food’s already there.

But if they suddenly go:

“Actually I feel like pasta instead of rice…”

…yeah, you’re screwed XD
You’re starting from scratch.

JIT (Just in Time) is the opposite.

You’re like:

“Tell me what you want, I’ll make it right now.”

Flexible? Yes.
Fast? …depends how hungry they are ;)

Flutter basically looked at both and said:

“Why not use both where they make sense?”

And that’s exactly what it does.

Debug Mode — JIT and the Dart VM

When you run:

flutter run

Your code is NOT compiled to native machine code.

Yeah — surprise.

Instead, Dart takes a completely different route.

The Compilation Pipeline

Your Dart code first goes through something called the CFE (Common Frontend).

Sounds fancy, but it’s basically:

parsing your code
checking types
resolving imports

And then it produces something called a Kernel AST.

Think of it like:

not source code, not machine code… but a structured “meaning” of your program

This gets saved as .dill files (Dart Intermediate Language).

From here, the Dart VM takes over.

Tiered JIT — This Is Where It Gets Spicy

The Dart VM doesn’t just compile everything upfront.

Because that would be dumb.

Why compile everything when half your code might never even run?

So it uses tiers:

Tier 0 — “Just run it bro”

Runs in an interpreter
No compilation
Starts instantly

Downside? Slow af.

But meanwhile, the VM is silently watching:

what functions are called
what types are used
which paths are hot

Tier 1 — “Okay this seems important”

Once a function gets called enough times:

it gets compiled to native code
but not heavily optimized

Faster than interpreter, but still warming up.

Tier 2 — “Alright I know your patterns now”

This is where things get spicy!

Now the VM has enough data to go:

“Cool, I trust this pattern.”

So it starts making bold assumptions.

Example:

If add(a, b) has only ever seen integers…

It goes:

“I’m skipping type checks. We going full speed.”

But what if suddenly a double shows up?

Boom.

Deoptimization.

throws away optimized code
falls back
re-learns

No drama. Just adapts.

The Real Trick

Cold code → stays cheap
Hot code → gets optimized like crazy

You only pay cost where it actually matters.

Hot Reload — The Real MVP

This is where JIT absolutely flexes.

You change a widget color → hit save.

Here’s what happens behind the scenes:

Only changed code gets recompiled
Sent to Dart VM over WebSocket
VM patches functions in-place
Flutter re-runs build()

And here’s the crazy part:

Your app state stays exactly the same

scroll position? safe
form input? safe
counters? safe

Because state lives in memory (heap), and you’re only swapping instructions.

That’s why hot reload feels like magic.

Why Debug Mode Feels Slow

It’s not just JIT.

Debug mode has extra baggage:

No tree shaking → everything included
Assertions ON → extra checks
DevTools hooks running
No aggressive optimizations
Constant profiling

Basically:

Debug mode = comfort + visibility
Release mode = speed + violence

Release Mode — AOT and Native Code

Now things change completely.

flutter build apk --release

No VM games anymore.

This is full AOT mode.

The Compilation Pipeline (Again, But Different Ending)

Same start:

Dart → CFE → Kernel AST

But now instead of VM → it goes to:

gen_snapshot (AOT compiler)

Type Flow Analysis — The Big Brain Move

Unlike JIT, AOT cannot guess.

No safety net. No “fix later”.

So it does something called Type Flow Analysis (TFA):

traces every possible path in your app
figures out what types can exist where
removes anything unreachable

Now the compiler can actually be bold:

inline functions
remove dead code
skip dynamic checks
devirtualize calls

Result?

Extremely optimised native machine code

What’s Inside Your APK?

If you unzip it, you’ll see something like:

your_app.apk
├── lib/
│   ├── arm64-v8a/
│   │   ├── libapp.so        ← YOUR code (compiled)
│   │   └── libflutter.so    ← Flutter engine
├── assets/
├── AndroidManifest.xml
└── classes.dex              ← tiny Android entry point

That classes.dex?

Not your app logic.

It’s just Android saying:

“Okay Flutter, you take over now.”

After that:
-->Flutter engine loads libapp.so
--> CPU runs your code directly

No VM. No interpreter. No waiting.

Why Hot Reload Is Impossible Here

In release mode:

no Dart VM
no runtime patching
no WebSocket updates

It’s just static native code.

So yeah…

--> Want changes? Rebuild. Reinstall. Done.

Profile Mode — Quick Side Note

flutter run --profile

This is the middle ground:

AOT performance
but still profiling tools available

Use it when you want real performance numbers without debug slowdown.

Why Flutter Hits Different

This is where things get really interesting.

React Native:

JS runs in the engine
communicates via bridge
data serialized/deserialized
async overhead

Flutter:

Dart → native machine code
talks directly to rendering engine
draws everything itself

No bridge. No middleman.

Flutter literally went:

“We’ll just render everything ourselves.”

And honestly?

Yeah… kinda insane.

The Mental Model

If you take one thing away, let it be this:

Debug mode → Dart VM is alive

dynamic
patchable
flexible
hot reload

Release mode → Dart VM is gone

static
precompiled
fast af
no flexibility

Flutter gives you both.

JIT for development speed
AOT for runtime performance

Compilation never disappears.

It just moves to where it makes the most sense.

From Spaghetti to Structure: Why I Migrated My Production Flutter App to Clean Architecture

Wed, 01 Apr 2026 04:48:07 +0000

"First make it work, then make it beautiful and robust."

I'm a junior dev. I built a real app — Anahad — that real people use. And for a while, I was proud of it.

Then it grew. And I wasn't so proud anymore.

This isn't a textbook post about Clean Architecture. This is the story of what broke, why I finally made the switch, and what actually clicked for me — told by someone who was in the trenches with a messy codebase and had to ship features at the same time.

The Mess I Was Living In

Picture this: 6 features. Each with their own screens, widgets, blocs, services, and utils — all distributed across a directory structure that looked neat on day one and became a labyrinth by month three.

Most screens were monoliths — all-in-one files with UI and logic tangled together. The ones that did use components? Everything went into a global widgets/ directory. So you'd have prop drilling across three levels just to pass something that one widget needed. Tracking the flow of data meant hopping between directories, mentally stitching together a picture of how things connected.

Error handling was... creative. I'd built my own AsyncResult<Success, Error> sealed class — functional programming vibes without the actual library. It worked at the service layer, but it was an island. Nothing else was consistent.

And the worst part? My services were tightly coupled to Dio and the remote API. No abstraction. No interface. You couldn't mock anything. You couldn't test anything. If Dio failed, the whole thing failed, and you had to dig to figure out why.

The moment I truly felt it was when I had to trace a bug and found myself drilling through 5 directories just to understand the flow. That's when I knew — this isn't scaling. This is surviving.

What Is Flutter Clean Architecture, Actually?

Before I get into the migration, let me walk you through the structure — because once it clicked, I couldn't unsee it.

Clean Architecture splits your app into three layers:

Presentation Layer

This is everything the user sees and touches.

Screens — Your UI pages
Widgets — Reusable UI components
Bloc — State management; the brain between UI and business logic

The Bloc only talks to the Domain layer. It doesn't know where data comes from. Doesn't care.

Domain Layer

This is the pure heart of your app. No Flutter. No Dio. No Firebase. Just Dart.

Entities — Plain Dart classes representing your core data models
Use Cases — Single-responsibility classes that each do one thing (e.g., LoginUseCase, FetchUserProfileUseCase)
Repository (Interface) — Abstract contracts defining what data operations exist, not how they work

This layer has zero dependencies on anything external. It's the most stable, most testable code in your app.

️ Data Layer

This is where the real world connects.

Models — Extend your Entities; handle JSON serialization, API mapping
Repository (Implementation) — Implements the Domain's repository interface
Data Sources — Remote (Dio, Firebase) and Local (Hive, SQLite)

The magic line? The Repository Implementation delegates data fetching to the datasource. The domain doesn't care if it's coming from the internet or a local cache.

Bloc → UseCase → Repository Interface
                        ↑
              Repository Implementation → Remote / Local Datasource

The Migration: Incremental, Not a Rewrite

Here's the thing nobody tells you: you don't have to nuke your codebase.

I had features to ship. Users on the app. I couldn't just disappear for two weeks and "do clean architecture." So I went incremental.

I started with the auth flow — the most self-contained, most critical part of the app. My service methods were already well-written, so the migration was mostly structural:

Converted service methods into Use Cases
Moved Dio calls into a RemoteDataSource
Created a Repository Implementation that satisfied the Domain's abstract interface
Wired the Bloc to talk to the Use Case instead of the service directly

It wasn't that hard, honestly. But the payoff was immediate.

Now if I want to add offline support to Anahad? I create a LocalDataSource, and the Repository Implementation switches between them. The Bloc doesn't change. The Use Cases don't change. The Domain doesn't even know it happened.

That's the beauty.

fpdart and Functional Programming in Use Cases

Coming from a Rust background, I was already comfortable with Option and Result types. I'd even hacked together my own AsyncResult<Success, Error> sealed class before this migration.

When I discovered fpdart, it was like: oh, this is just the proper version of what I was already doing.

In my Use Cases, I now use Either<Failure, Success> for all return types. Left is failure, right is success — and you chain transformations cleanly without nested try-catches or nullable hell.

// Use Case
class LoginUseCase {
  final AuthRepository repository;

  LoginUseCase(this.repository);

  Future<Either<Failure, User>> call(LoginParams params) async {
    return await repository.login(params.email, params.password);
  }
}

// In the Bloc
final result = await loginUseCase(LoginParams(email: email, password: password));

result.fold(
  (failure) => emit(AuthError(failure.message)),
  (user)    => emit(AuthSuccess(user)),
);

No try-catch spaghetti. No "did this return null or did it actually fail?" ambiguity. The types tell the story.

The "Aha" Moment

I'll be honest — my first reaction to Clean Architecture was "this is way too much boilerplate."

Why write a Use Case class that just calls a repository method? Why create an abstract interface when I could just use the implementation directly? Seemed like over-engineering for the sake of it.

Then I migrated the auth flow. And something just... clicked.

I was looking at my Bloc, and I realized: this Bloc has no idea where the user data comes from. It doesn't import Dio. It doesn't know about Firebase. It just calls loginUseCase() and reacts to the result.

Before this, I couldn't test anything because everything was tightly coupled. The service needed Dio, Dio needed a real network, the network needed... you get it. Now, because the Repository is an abstract interface, I can mock it in tests trivially:

class MockAuthRepository extends Mock implements AuthRepository {}

That's it. Inject it. Test your Use Cases in complete isolation.

Ambiguity went away. I know exactly what each file does, what it depends on, and what it's responsible for. When something breaks, I know which layer to look at.

Should You Use Clean Architecture for Every App?

No. Please don't.

If you're building a weekend project or learning Flutter for the first time, don't start with Clean Architecture. You'll spend more time setting up the structure than building the thing, and you'll learn why the architecture exists without ever feeling the pain it solves.

The pain is the teacher.

Build the app. Ship it. Let it grow. Feel the moment where you're drilling through 5 directories to trace a bug, where you can't mock a thing for testing, where adding one feature means touching 8 files in 6 different folders.

Then reach for Clean Architecture. Because then you'll understand it — not just intellectually, but in your bones.

The architecture exists to solve real problems. Let the problems teach you first.

Quick Reference: The Layer Cheat Sheet

Layer	Contains	Depends On
Presentation	Screens, Widgets, Bloc	Domain only
Domain	Entities, Use Cases, Repository Interface	Nothing (pure Dart)
Data	Models, Repository Impl, Data Sources	Domain interfaces

What's Next for Anahad

Migrating the remaining 5 features incrementally
Adding a proper logging layer
Writing actual unit tests now that mocking is possible
Maybe offline support — and thanks to clean architecture, it'll be a datasource swap, not a rewrite

If you're a fellow junior dev with a production app that's starting to smell — I see you. You don't have to have everything figured out from day one. Build it, feel the pain, then build it better.

That's not a failure. That's engineering.

Built with love (and a lot of refactoring) while working on Anahad.
Hit me up on Twitter/X if this resonated — always happy to talk Flutter, architecture, or why Rust spoils you for everything else.

Flutter Performance Optimization 2026 (Make Your App 10x Faster + Best Practices)

Sun, 22 Mar 2026 20:11:53 +0000

Hey guys, Samuel here again. One of the crucial aspects of mobile app development is performance optimization to ensure the app is usable even on low-quality devices and delivers a very good user experience, which is what we will be looking into today.

To optimize a Flutter application's performance, focus on minimizing unnecessary widget rebuilds, using efficient rendering techniques, and managing resources effectively. The key steps involve leveraging built-in tools for profiling, optimizing UI code, and improving data handling efficiency.

Performance Diagnosis

Before optimizing, you must identify bottlenecks using the right tools:

Run in Profile Mode: Always profile your app in profile mode on a physical device, as debug mode performance is not representative of the final release build.

flutter run --profile

Flutter DevTools: Use the Flutter DevTools suite (Performance, Memory, Network tabs) to analyze frame rendering times, CPU usage, memory allocation, and network latency.
Performance Overlay: Use the built-in PerformanceOverlay widget or press 'P' in the terminal while running the app to see real-time UI and GPU thread frame times. Red bars indicate "jank" (dropped frames).

MaterialApp(
  ...
  showPerformanceOverlay: true,
  ...
),

Most performance issues stem from inefficient UI code.

Minimize Widget Rebuilds:

- Use const constructors for widgets that don't change to allow Flutter to reuse them at compile time, reducing runtime overhead.

const Text("This widget would not rebuild"),

- Refactor large build methods into smaller, dedicated StatelessWidget or StatefulWidget classes to localize the scope of rebuilds.

- Use state management solutions (like Provider, Riverpod, or BLoC) with Consumer or Selector to ensure only the necessary parts of the UI rebuild when the state changes.

- Use ValueListenableBuilder or AnimatedBuilder for fine-grained updates instead of calling setState() on large widgets.

Optimize Lists and Animations:

- For long lists, use ListView.builder (or SliverList) to lazy load items, building them only when they become visible on screen.

ListView.builder(
  shrinkWrap: true,
  physics: const NeverScrollableScrollPhysics(),
  itemCount: 1,
  itemBuilder: (context, index) {
    return ListTile();
  },
),

// OR

 SliverList.builder(
  itemBuilder: (context, index) =>
      Container(height: 100),
 ),

- Wrap complex, frequently animating widgets in a RepaintBoundary to isolate their repainting from the rest of the UI.

RepaintBoundary(child: ...),

- Avoid using the Opacity widget directly for animations; prefer FadeTransition instead, as it's more performant.

Resource and Data Management

Efficiently handle data, images, and heavy computations to prevent UI freezes.

Image Handling:

- Use the cached_network_image package for images from the network to implement efficient caching and reduce network requests.

- Compress images before bundling them with the app and loading them at optimal resolutions.

Asynchronous Operations:

- Use async/await, FutureBuilder, and StreamBuilder to perform network requests and other I/O operations without blocking the main UI thread.

- For CPU-intensive tasks (e.g., heavy data processing), use Isolates via the compute function to run them on a separate thread.
Memory Management:

- Always dispose of controllers (AnimationController, TextEditingController, etc.), StreamSubscription instances, and other resources in the dispose() Method of your StatefulWidget to prevent memory leaks.

Network Optimization:

- Implement data pagination for large datasets to avoid fetching all data at once.
- Cache API responses to reduce the number of network calls and improve perceived performance.

App Size and Build Optimizations

Reduce App Size:

- Remove unused assets and libraries ("tree-shaking").
- Use the flutter build apk --split-per-abi command to generate smaller APKs for different device architectures.

Enable Release Mode: Always verify final performance using flutter run --release or by building the app in release mode.

That's it! You've fully optimized your Flutter app performance if you follow all the principles. If you have any questions, make sure to drop them in the comment section.

Join Free Newsletter: https://techwithsam.dev/newsletter

Samuel Adekunle, Tech With Sam YouTube

How a Bug Report Led Me to Give Flutter Developers Full Control of Crisp Chat Modals on iOS

Sun, 15 Mar 2026 07:25:41 +0000

One of the things I enjoy most about maintaining open-source software is that sometimes the best improvements start with something very small.

A simple bug report.
A curious investigation.
And sometimes… a new feature idea.

This story started exactly like that.

The Bug Report That Started Everything

While reviewing issues for the Flutter Crisp Chat plugin, I noticed a report opened by Nikita Alexeev.

The title immediately caught my attention:

“Taps pass through chat modal to underlying UI on iOS 13+.”

That sounded strange.

A modal should block interactions with the UI behind it. So how could taps reach the Flutter app underneath?

I opened the issue and read the details carefully.

The behavior was simple but frustrating:

Open the Crisp chat on an iPhone
Tap near the top area of the chat
Suddenly the Flutter UI behind it reacts

Buttons could be pressed. Navigation could trigger. All while the chat was still visible.

That’s definitely not the experience anyone wants when they open a support chat.

So I started digging.

Learning Something Interesting About iOS

While reading the issue discussion and the explanation from Nikita Alexeev, I discovered something interesting about iOS.

Starting with iOS 13, Apple changed how modal presentations behave by default.

Before iOS 13, most modals were presented using:

.fullScreen

Which means the modal covers the entire screen. Nothing behind it is visible, and more importantly, nothing behind it can receive touches.

But iOS 13 introduced a new default style:

.pageSheet

This creates the modern sheet-style UI where the modal slides up from the bottom and leaves part of the background visible.

It looks elegant and more native to modern iOS design.

But there was a catch.

In this case, the dimmed background area was still allowing touch events to reach the Flutter UI underneath.

That explained exactly why users were accidentally triggering buttons behind the chat window.

Suddenly the bug made perfect sense.

The Pull Request That Fixed It

Soon after reporting the issue, Nikita Alexeev submitted a pull request with a very straightforward fix.

Instead of relying on the default modal style, he forced the chat view controller to use full screen presentation.

The change looked like this:

let chatVC = ChatViewController()
chatVC.modalPresentationStyle = .fullScreen
viewController.present(chatVC, animated: true)

It was a very small change, but it solved the problem completely.

By forcing .fullScreen, the chat now covered the entire screen again, which meant no touches could leak through to the Flutter UI behind it.

The issue was fixed.

But while reviewing the pull request, a new idea came to my mind.

The Moment the Idea Appeared

Yes, .fullScreen solved the issue.

But iOS actually supports several modal presentation styles.

For example:

.fullScreen
.pageSheet
.formSheet
.overFullScreen
.overCurrentContext
.popover

Different apps use different modal styles depending on their design.

Some apps prefer full screen.

Some prefer sheet-style modals.

Some prefer overlays.

So instead of hardcoding .fullScreen, I thought:

What if Flutter developers could choose the modal style themselves?

That way:

The touch-through bug stays fixed
Developers get flexibility
The plugin becomes more powerful

That’s when the idea shifted from a bug fix to a developer-focused feature.

Turning the Idea into a Feature

To make this possible, I needed to expose the modal presentation style all the way from Flutter to the native iOS implementation.

So I started with the Flutter configuration.

Step 1 — Extending the Flutter Configuration

First, I added a new enum to represent the iOS modal styles.

enum ModalPresentationStyle {
  fullScreen,
  pageSheet,
  formSheet,
  overFullScreen,
  overCurrentContext,
  popover,
}

Then I added it to the CrispConfig class.

class CrispConfig {
  final String websiteID;
  final String? tokenId;
  final ModalPresentationStyle? modalPresentationStyle;

  CrispConfig({
    required this.websiteID,
    this.tokenId,
    this.modalPresentationStyle,
  });
}

Now Flutter developers could specify how the chat modal should appear.

Step 2 — Bridging the Setting to iOS

Next, I needed to convert that Flutter value into a native iOS presentation style.

Inside the Swift plugin code, I mapped the configuration to UIModalPresentationStyle.

switch modalPresentationStyleString {
case "fullScreen":
    modalPresentationStyle = .fullScreen
case "pageSheet":
    modalPresentationStyle = .pageSheet
case "formSheet":
    modalPresentationStyle = .formSheet
case "overFullScreen":
    modalPresentationStyle = .overFullScreen
case "overCurrentContext":
    modalPresentationStyle = .overCurrentContext
case "popover":
    modalPresentationStyle = .popover
default:
    modalPresentationStyle = .fullScreen
}

This ensured a safe default while still allowing flexibility.

Step 3 — Applying the Configuration

Finally, instead of hardcoding .fullScreen, the plugin now uses the configured style.

let chatVC = ChatViewController()
chatVC.modalPresentationStyle = crispConfig.modalPresentationStyle

viewController.present(chatVC, animated: true)

Now Flutter developers have full control over the presentation style.

Making the Feature Easy to Discover

After implementing the improvements, I wanted to make sure developers could easily explore and understand them.

So I also improved the developer experience around the plugin.

I added an interactive demo inside the example app where developers can test different iOS modal styles.

There’s a button called “iOS Modal Style Demo” that opens the chat using different presentation styles so developers can see how each one behaves.

I also updated the documentation to clearly explain:

How iOS modal presentation works
Why .fullScreen fixes the touch-through issue
How to configure the modal style in Flutter

What Developers Gain From This

What started as a small bug report now gives Flutter developers several benefits.

Better User Experience

No more accidental taps on the UI behind the chat.

Flexible Modal Presentation

Developers can choose the modal style that fits their app design.

Platform Awareness

These changes only affect iOS behavior, while Android remains unchanged.

What I Love About Open Source

This experience reminded me why I enjoy maintaining open-source projects.

Sometimes improvements don’t start with big feature ideas.

They start with a simple issue report.

A developer noticing something strange.

A pull request proposing a fix.

And a moment of curiosity that turns a bug fix into something better.

So huge thanks to Nikita Alexeev for reporting the issue and submitting the original fix that inspired this improvement.

Try It Yourself

If you’re using the Flutter Crisp Chat plugin, you can try the new configuration like this:

final config = CrispConfig(
  websiteID: 'YOUR_WEBSITE_ID',
  modalPresentationStyle: ModalPresentationStyle.pageSheet,
  enableNotifications: false,
);

And if you’re curious to see how each modal style behaves, check out the example app in the repository.

Sometimes the best features don’t start with a roadmap.

They start with a bug report…
and a little curiosity.

The Hidden Gem of Flutter Lists: Unlocking scrollable_positioned_list's Superpowers

Tue, 10 Feb 2026 19:56:35 +0000

As Flutter developers, we've all faced the common challenge: building lists that need more control than the standard ListView provides. Whether it's scrolling to a specific index, tracking which items are visible, or implementing complex navigation patterns, Flutter's built-in widgets sometimes leave us wanting more.

Enter scrollable_positioned_list – a powerful yet often-overlooked package from Google's flutter.widgets repository that solves these problems elegantly.

In this comprehensive guide, we'll explore the hidden gems of this package and demonstrate how it can transform your Flutter applications.

Why scrollable_positioned_list Matters

The Problem with Standard ListView

Flutter's ListView is excellent for basic scrolling, but it has significant limitations:

No built-in scrollToIndex() – You must develop custom solutions to measure element offsets
No visibility detection – Determining which items are currently visible requires complex workarounds
Limited programmatic control – Jumping to specific items is non-trivial

The scrollable_positioned_list Solution

This package addresses all these limitations with a clean, well-documented API that maintains the familiar ListView.builder pattern while adding powerful capabilities.

According to the official documentation, this widget allows scrolling to a specific item and determining what items are currently visible – exactly what advanced Flutter applications need.

Installation and Setup

Add the package to your pubspec.yaml:

dependencies:
  scrollable_positioned_list: ^0.3.8

Then import it:

import 'package:scrollable_positioned_list/scrollable_positioned_list.dart';

Hidden Gem #1: Programmatic Scrolling with scrollToIndex

The most powerful feature is the ability to scroll to any item programmatically – functionality that standard ListView simply doesn't provide.

class ScrollableListExample extends StatefulWidget {
  @override
  _ScrollableListExampleState createState() => _ScrollableListExampleState();
}

class _ScrollableListExampleState extends State<ScrollableListExample> {
  final ItemScrollController _itemScrollController = ItemScrollController();
  final ItemPositionsNotifier _itemPositionsNotifier = ItemPositionsNotifier();
  final List<String> _items = List.generate(100, (index) => 'Item ${index + 1}');

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('ScrollablePositionedList Demo')),
      body: Column(
        children: [
          Padding(
            padding: const EdgeInsets.all(16.0),
            child: Row(
              mainAxisAlignment: MainAxisAlignment.spaceEvenly,
              children: [
                ElevatedButton(onPressed: () => _scrollToIndex(0), child: const Text('To Start')),
                ElevatedButton(onPressed: () => _scrollToIndex(_items.length - 1), child: const Text('To End')),
                ElevatedButton(onPressed: () => _scrollToIndex(49), child: const Text('To Middle')),
              ],
            ),
          ),
          Expanded(
            child: ScrollablePositionedList.builder(
              itemCount: _items.length,
              itemScrollController: _itemScrollController,
              itemPositionsNotifier: _itemPositionsNotifier,
              itemBuilder: (context, index) => ListTile(
                title: Text(_items[index]),
                subtitle: Text('Position: ${index + 1}'),
              ),
            ),
          ),
        ],
      ),
    );
  }

  void _scrollToIndex(int index) {
    _itemScrollController.scrollTo(index: index, duration: const Duration(seconds: 2), curve: Curves.easeInOutCubic);
  }
}

Advanced Options:

// Jump immediately (no animation)
void _jumpToIndex(int index) => _itemScrollController.jumpTo(index: index);

// Scroll with custom alignment (0.0 = top, 0.5 = center, 1.0 = bottom)
void _scrollToCenter(int index) {
  _itemScrollController.scrollTo(index: index, alignment: 0.5, duration: const Duration(milliseconds: 500));
}

Hidden Gem #2: ItemPositionListener – Tracking What's Visible

The ItemPositionListener monitors which items are visible – perfect for reading progress, lazy loading, or scroll-synced animations.

class ReadingProgressExample extends StatefulWidget {
  @override
  _ReadingProgressExampleState createState() => _ReadingProgressExampleState();
}

class _ReadingProgressExampleState extends State<ReadingProgressExample> {
  final ItemPositionsNotifier _itemPositionsNotifier = ItemPositionsNotifier();
  double _readingProgress = 0.0;

  @override
  void initState() {
    super.initState();
    _itemPositionsNotifier.itemPositions.addListener(_updateProgress);
  }

  @override
  void dispose() {
    _itemPositionsNotifier.itemPositions.removeListener(_updateProgress);
    super.dispose();
  }

  void _updateProgress() {
    final positions = _itemPositionsNotifier.itemPositions.value;
    if (positions.isNotEmpty) {
      final minIndex = positions.where((p) => p.itemLeadingEdge < 1).reduce((min, p) => p.itemLeadingEdge < min.itemLeadingEdge ? p : min).index;
      final maxIndex = positions.where((p) => p.itemTrailingEdge > 0).reduce((max, p) => p.itemTrailingEdge > max.itemTrailingEdge ? p : max).index;
      setState(() => _readingProgress = ((minIndex + maxIndex) / 200).clamp(0.0, 1.0));
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Reading Progress'), bottom: PreferredSize(preferredSize: const Size.fromHeight(4), child: LinearProgressIndicator(value: _readingProgress))),
      body: ScrollablePositionedList.builder(itemCount: 100, itemPositionsNotifier: _itemPositionsNotifier, itemBuilder: (context, index) => Padding(padding: const EdgeInsets.all(16.0), child: Text('Chapter ${index + 1}', style: const TextStyle(fontSize: 18)))),
    );
  }
}

Detecting Fully Visible Items:

bool isItemFullyVisible(ItemPosition position) => position.itemLeadingEdge >= 0 && position.itemTrailingEdge <= 1;

List<int> getFullyVisibleIndices() => _itemPositionsNotifier.itemPositions.value.where(isItemFullyVisible).map((p) => p.index).toList();

Hidden Gem #3: Variable Height Items Support

This package handles items of varying heights gracefully – crucial for dynamic content apps.

class VariableHeightListExample extends StatelessWidget {
  final ItemScrollController _scrollController = ItemScrollController();
  final List<_ContentItem> _items = List.generate(50, (index) {
    final lines = (index % 5) + 1;
    return _ContentItem(title: 'Article ${index + 1}', content: 'This article has $lines lines.\n' * lines);
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Variable Height List'), actions: [
        IconButton(icon: const Icon(Icons.arrow_downward), onPressed: () => _scrollController.scrollTo(index: _items.length - 1, duration: const Duration(seconds: 2)))
      ]),
      body: ScrollablePositionedList.builder(
        itemCount: _items.length,
        itemScrollController: _scrollController,
        itemBuilder: (context, index) => Card(
          margin: const EdgeInsets.all(8),
          child: Padding(
            padding: const EdgeInsets.all(16),
            child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
              Text(_items[index].title, style: Theme.of(context).textTheme.titleLarge),
              const SizedBox(height: 8), Text(_items[index].content)
            ]),
          ),
        ),
      ),
    );
  }
}

class _ContentItem {
  final String title, content;
  _ContentItem({required this.title, required this.content});
}

Hidden Gem #4: Scroll Offset Tracking

class ScrollOffsetExample extends StatefulWidget {
  @override
  _ScrollOffsetExampleState createState() => _ScrollOffsetExampleState();
}

class _ScrollOffsetExampleState extends State<ScrollOffsetExample> {
  final ItemPositionsNotifier _positionsNotifier = ItemPositionsNotifier();
  final ItemScrollController _scrollController = ItemScrollController();
  double _currentScrollOffset = 0.0;

  @override
  void initState() {
    super.initState();
    _positionsNotifier.itemPositions.addListener(() {
      final positions = _positionsNotifier.itemPositions.value;
      if (positions.isNotEmpty) setState(() => _currentScrollOffset = positions.first.itemLeadingEdge);
    });
  }

  @override
  void dispose() {
    _positionsNotifier.itemPositions.removeListener(() {});
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Offset: ${_currentScrollOffset.toStringAsFixed(2)}')),
      body: Stack(
        children: [
          Positioned(top: -_currentScrollOffset * 0.5, left: 0, right: 0, child: Container(height: 200, decoration: BoxDecoration(gradient: LinearGradient(colors: [Colors.blue.shade200, Colors.purple.shade200])))),
          ScrollablePositionedList.builder(
            itemCount: 50,
            itemScrollController: _scrollController,
            itemPositionsNotifier: _positionsNotifier,
            padding: const EdgeInsets.only(top: 150),
            itemBuilder: (context, index) => ListTile(title: Text('Item ${index + 1}'), subtitle: Text('Offset: ${_currentScrollOffset.toStringAsFixed(2)}')),
          ),
        ],
      ),
    );
  }
}

Implement a table of contents that highlights the current section – perfect for documentation sites.

class ScrollSpyExample extends StatefulWidget {
  @override
  _ScrollSpyExampleState createState() => _ScrollSpyExampleState();
}

class _ScrollSpyExampleState extends State<ScrollSpyExample> {
  final ItemScrollController _scrollController = ItemScrollController();
  final ItemPositionsNotifier _positionsNotifier = ItemPositionsNotifier();
  final List<String> _sections = List.generate(20, (index) => 'Section ${index + 1}');
  int _activeSection = 0;

  @override
  void initState() {
    super.initState();
    _positionsNotifier.itemPositions.addListener(() {
      final positions = _positionsNotifier.itemPositions.value;
      if (positions.isNotEmpty) {
        final mostVisible = positions.reduce((a, b) => (a.itemLeadingEdge.abs() + a.itemTrailingEdge.abs()) / 2 < (b.itemLeadingEdge.abs() + b.itemTrailingEdge.abs()) / 2 ? a : b);
        if (_activeSection != mostVisible.index) setState(() => _activeSection = mostVisible.index);
      }
    });
  }

  @override
  void dispose() {
    _positionsNotifier.itemPositions.removeListener(() {});
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Scroll Spy Navigation')),
      body: Row(
        children: [
          Container(
            width: 200,
            color: Colors.grey[100],
            child: ListView.builder(
              itemCount: _sections.length,
              itemBuilder: (context, index) {
                final isActive = index == _activeSection;
                return ListTile(
                  title: Text(_sections[index], style: TextStyle(fontWeight: isActive ? FontWeight.bold : FontWeight.normal, color: isActive ? Colors.blue : Colors.black87)),
                  selected: isActive,
                  onTap: () => _scrollController.scrollTo(index: index, duration: const Duration(milliseconds: 300), alignment: 0.0),
                );
              },
            ),
          ),
          Expanded(
            child: ScrollablePositionedList.builder(
              itemCount: _sections.length,
              itemScrollController: _scrollController,
              itemPositionsNotifier: _positionsNotifier,
              itemBuilder: (context, index) => Container(height: 300, padding: const EdgeInsets.all(24), child: Text(_sections[index], style: Theme.of(context).textTheme.headlineMedium)),
            ),
          ),
        ],
      ),
    );
  }
}

Common Pitfalls and Solutions

Pitfall 1: Controller Not Attached

Problem: Calling scrollTo before the controller is attached.

Solution:

void _safeScrollTo(int index) {
  if (_itemScrollController.isAttached) {
    _itemScrollController.scrollTo(index: index);
  } else {
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (_itemScrollController.isAttached) _itemScrollController.scrollTo(index: index);
    });
  }
}

Pitfall 2: CustomScrollView Incompatibility

Problem: Doesn't work well inside CustomScrollView with other slivers.

Solution: Use as standalone or consider super_sliver_list for complex sliver scenarios. See GitHub Issue #32.

Pitfall 3: Alignment Confusion

Solution: The alignment parameter specifies where the target item positions:

0.0 = Top of viewport
0.5 = Center of viewport
1.0 = Bottom of viewport

Feature	ListView	scrollable_positioned_list	CustomScrollView
Basic scrolling	✅	✅	✅
scrollToIndex()	❌	✅	❌
Visibility detection	❌	✅	❌
Variable height items	✅	✅	✅
Custom sliver integration	❌	❌	✅

Use scrollable_positioned_list for: scroll-to-index, visibility tracking, scroll-offset animations, reading progress, scroll spy navigation.

Use standard ListView for: basic scrolling, maximum performance, CustomScrollView integration.

Real-World Example: Music Player with Queue

class MusicPlayerQueue extends StatefulWidget {
  const MusicPlayerQueue({Key? key}) : super(key: key);
  @override
  _MusicPlayerQueueState createState() => _MusicPlayerQueueState();
}

class _MusicPlayerQueueState extends State<MusicPlayerQueue> {
  final ItemScrollController _scrollController = ItemScrollController();
  final ItemPositionsNotifier _positionsNotifier = ItemPositionsNotifier();
  final List<Song> _playlist = List.generate(50, (index) => Song(title: 'Track ${index + 1}', artist: 'Artist ${(index % 10) + 1}', duration: Duration(minutes: 3, seconds: (index * 7) % 60)));
  int _currentTrackIndex = 0;
  bool _isPlaying = false;

  void _playTrack(int index) {
    setState(() => _currentTrackIndex = _currentTrackIndex = index);
    _scrollController.scrollTo(index: index, alignment: 0.5, duration: const Duration(milliseconds: 400), curve: Curves.easeInOut);
  }

  void _nextTrack() => _playTrack((_currentTrackIndex + 1) % _playlist.length);
  void _previousTrack() => _playTrack((_currentTrackIndex - 1 + _playlist.length) % _playlist.length);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Music Player'), actions: [
        IconButton(icon: Icon(_isPlaying ? Icons.pause : Icons.play_arrow), onPressed: () => setState(() => _isPlaying = !_isPlaying))
      ]),
      body: Column(
        children: [
          Container(
            padding: const EdgeInsets.all(16),
            color: Colors.blue.shade50,
            child: Row(children: [
              const Icon(Icons.music_note, size: 48),
              const SizedBox(width: 16),
              Expanded(child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
                Text(_playlist[_currentTrackIndex].title, style: const TextStyle(fontWeight: FontWeight.bold)),
                Text(_playlist[_currentTrackIndex].artist),
                Text(_formatDuration(_playlist[_currentTrackIndex].duration))
              ])),
              IconButton(icon: const Icon(Icons.skip_previous), onPressed: _previousTrack),
              IconButton(icon: const Icon(Icons.skip_next), onPressed: _nextTrack)
            ]),
          ),
          Expanded(
            child: ScrollablePositionedList.builder(
              itemCount: _playlist.length,
              itemScrollController: _scrollController,
              itemPositionsNotifier: _positionsNotifier,
              itemBuilder: (context, index) {
                final song = _playlist[index];
                final isPlaying = index == _currentTrackIndex;
                return ListTile(
                  leading: CircleAvatar(backgroundColor: isPlaying ? Colors.blue : Colors.grey[300], child: Icon(isPlaying ? (_isPlaying ? Icons.pause : Icons.play_arrow) : Icons.music_note, color: isPlaying ? Colors.white : Colors.black54)),
                  title: Text(song.title, style: TextStyle(fontWeight: isPlaying ? FontWeight.bold : FontWeight.normal, color: isPlaying ? Colors.blue : null)),
                  subtitle: Text(song.artist),
                  trailing: Text(_formatDuration(song.duration)),
                  onTap: () => _playTrack(index),
                );
              },
            ),
          ),
        ],
      ),
    );
  }

  String _formatDuration(Duration d) => '${d.inMinutes}:${d.inSeconds.toString().padLeft(2, '0')}';
}

class Song {
  final String title, artist;
  final Duration duration;
  Song({required this.title, required this.artist, required this.duration});
}

Key Takeaways

The scrollable_positioned_list package is a hidden gem every Flutter developer should know:

Solves Real Problems – Addresses ListView limitations without complexity
Clean API – Familiar ListView.builder pattern with powerful features
Google-Maintained – Part of google/flutter.widgets repository
Production-Ready – Used in apps like API Dash
Feature-Rich – scrollToIndex(), visibility tracking, offset monitoring

Perfect for: playlist apps, documentation readers, chat apps, table of contents, any precise scroll control scenario.

Conclusion

The scrollable_positioned_list package fills a crucial gap in Flutter's ecosystem by providing scrollToIndex(), visibility tracking, and scroll offset monitoring – all while maintaining the familiar ListView.builder API. Try it in your next project!

Local MongoDB like database in flutter

Mon, 05 May 2025 17:07:35 +0000

FlutterDB

FlutterDB is a lightweight, SQLite-based document database for Flutter applications. It provides a MongoDB-like API for managing collections and documents while leveraging the performance benefits of SQLite.

Why do I build this?

So I am using MongoDB in my NodeJS application. Now I am building a chat application in Flutter, and for rendering performance, I thought I should store the messages locally and render a sliding window on it. Still, I have no luck finding a good local database that is flexible enough and also fast enough. And so I thought, why not build a MongoDB-like database in Flutter, which gets the job done. It's not a full-fledged MongoDB running locally, but it is similar to it, and most of the common tasks are going very well, as I tested.

Features

Document-oriented database with collections and documents
MongoDB-style query syntax and operations
Built on top of SQLite for performance and reliability
Unique ID generation for documents
Support for complex queries, updates, and aggregations
Batch operations for better performance

Installation

Add the following dependencies to your pubspec.yaml:

dependencies:
  flutterdb: ^0.0.1

Getting Started

Import the package:

import 'package:flutterdb/flutterdb.dart';

Initialize the database:

final db = FlutterDB();

Basic Usage

Working with Collections

// Create or get a collection
final users = await db.collection('users');

// List all collections
final collections = await db.listCollections();

// Drop a collection
await db.dropCollection('users');

CRUD Operations

Create

// Insert a single document
final userId = await users.insert({
  'name': 'John Doe',
  'email': '*Emails are not allowed*',
  'age': 30
});

// Insert multiple documents
final ids = await users.insertMany([
  {
    'name': 'Jane Smith',
    'email': '*Emails are not allowed*',
    'age': 25
  },
  {
    'name': 'Bob Johnson',
    'email': '*Emails are not allowed*',
    'age': 40
  }
]);

Read

// Find all documents in a collection
final allUsers = await users.find({});

// Find documents with a simple query
final adults = await users.find({'age': {'$gte': 18}});

// Find a document by ID
final user = await users.findById(userId);

// Count documents
final userCount = await users.count({'age': {'$gt': 30}});

Update

// Update a document by ID
await users.updateById(userId, {'status': 'active'});

// Update multiple documents
final updatedCount = await users.updateMany(
  {'age': {'$lt': 30}},
  {'status': 'young'}
);

Delete

// Delete a document by ID
await users.deleteById(userId);

// Delete multiple documents
final deletedCount = await users.deleteMany({'status': 'inactive'});

Advanced Queries

Comparison Operators

// Greater than
await users.find({'age': {'$gt': 30}});

// Less than or equal
await users.find({'age': {'$lte': 25}});

// Not equal
await users.find({'status': {'$ne': 'inactive'}});

// In array
await users.find({'role': {'$in': ['admin', 'moderator']}});

Logical Operators

// AND
await users.find({
  '$and': [
    {'age': {'$gte': 18}},
    {'status': 'active'}
  ]
});

// OR
await users.find({
  '$or': [
    {'role': 'admin'},
    {'permissions': {'$in': ['write', 'delete']}}
  ]
});

// NOR
await users.find({
  '$nor': [
    {'status': 'banned'},
    {'role': 'guest'}
  ]
});

Text Search

// Regex search
await users.find({'name': {'$regex': '^Jo'}});

// Simple text search
await users.find({'bio': {'$like': 'flutter developer'}});

Aggregation

final results = await users.aggregate([
  {'$match': {'status': 'active'}},
  {'$sort': {'age': -1}},
  {'$skip': 10},
  {'$limit': 20},
  {'$project': {
          'name': 1,
          'age': 1,
          'city': 1,
          '_id': 0,
               }
  },
  {'$group': {
          '_id': '\$city',
          'count': {'\$sum': 1}
        }
  },
]);

Best Practices

Performance Optimization

Use batch operations for multiple insertions or updates:

await users.insertMany(manyUsers); // Better than inserting one by one

Keep document size reasonable:
- Large documents can slow down performance
- Consider storing large binary data (images, files) separately
Create indexes for frequently queried fields:
- Currently, FlutterDB automatically indexes collection names
- Future versions may support custom indexes
Use appropriate queries:
- Finding by ID is faster than complex queries
- Limit results when possible using $limit

Data Structure

Use consistent schemas:
- While FlutterDB is schemaless, consistent document structures improve code maintainability
Choose good document IDs:
- Let FlutterDB generate IDs unless you have specific requirements
- Custom IDs should be unique and consistent
Handle relationships thoughtfully:
- For one-to-many relationships, consider embedding related data or using references

Error Handling

Always implement error handling:

try {
  await users.insert({'name': 'John'});
} catch (e) {
  print('Error inserting document: $e');
  // Handle error appropriately
}

Limitations

Not a full MongoDB replacement:
- Limited subset of MongoDB query operators
- Some complex aggregation operations not supported
Performance with large datasets:
- Best suited for mobile apps with moderate data size
- Consider pagination or limiting queries for large collections
No built-in encryption:
- Data is stored in plain text
- Consider additional encryption for sensitive data
Limited indexing options:
- Custom indexes not yet supported
- Consider query performance for large collections
No network synchronization:
- Local database only
- Implement your own sync solution if needed

Complete Example

import 'package:flutter/material.dart';
import 'package:flutterdb/flutterdb.dart';

class UserRepository {
  final FlutterDB _db = FlutterDB();
  late Future<Collection> _users;

  UserRepository() {
    _users = _db.collection('users');
  }

  Future<String> addUser(String name, String email, int age) async {
    final collection = await _users;
    return await collection.insert({
      'name': name,
      'email': email,
      'age': age,
      'createdAt': DateTime.now().toIso8601String(),
    });
  }

  Future<List<Map<String, dynamic>>> getAdultUsers() async {
    final collection = await _users;
    return await collection.find({
      'age': {'$gte': 18},
    });
  }

  Future<void> updateUserStatus(String id, String status) async {
    final collection = await _users;
    await collection.updateById(id, {
      'status': status,
      'updatedAt': DateTime.now().toIso8601String(),
    });
  }
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final userRepo = UserRepository();
  
  // Add a user
  final userId = await userRepo.addUser('Alice', '*Emails are not allowed*', 28);
  print('Added user with ID: $userId');
  
  // Update user status
  await userRepo.updateUserStatus(userId, 'premium');
  
  // Get all adult users
  final adults = await userRepo.getAdultUsers();
  for (var user in adults) {
    print('User: ${user['name']}, Age: ${user['age']}, Status: ${user['status']}');
  }
}

Future Enhancements

Custom indexing support
More aggregation pipeline operators
Full-text search capabilities
Data encryption options
Schema validation
Observable queries
Migration support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GNU AGPLv3 License - see the LICENSE file for details.

If you are searching for this keywords
"offline-first Flutter apps"
"local storage in Flutter"
"best local database Flutter"

your search ends here
I'd love your thoughts. Try FlutterDB in your next project and let me know how it goes! You can ⭐️ the GitHub repo or open an issue if you hit any snags.

Coder Legion - Recent posts tagged dart

flutter_skin Alpha — Material 3 Tokens, Live Preview & Typography | Remote Skin

flutter_skin — Live Remote Skin Engine Demo | Change Flutter Colors Without Rebu

Reflection in Dart

Stop Guessing Frame Drops: Passive Zero Overhead Performance Telemetry for Flutter

The Quiet Work Behind a Flutter Endpoint

The shape I keep repeating

Where things got slightly less boring

Why I do not let the UI talk directly to Dio

The service locator is where I check my work

One small detail that mattered more than expected

The endpoint constants are not just strings

What I noticed while wiring everything

The part I keep learning

The Day White Became a Bug

I Built a Complete Zomato-Style Food Delivery Platform in Flutter — Here's What I Learned

The Coordinated BLoC Pattern in Flutter — A Practical Guide

The Coordinated BLoC Pattern in Flutter — A Practical Guide

What Problem Does This Solve?

Mental Model

Architecture

Implementation

1. Events

Event Intent

2. States

3. The Coordination BLoC

The key idea

Dependency Injection (GetIt)

BLoC Providers

The Screen

Mistakes to Not Make

Mistake 1: Registering Handlers After Calling add()

Mistake 2: Using registerFactory

Rule

Mistake 3: Forgetting to Cancel Stream Subscriptions

Mistake 4: Forgetting .take(1)

Mistake 5: Mixing GetIt and context.read

Mistake 6: Leaving Half the Logic in the Screen

The Hidden Cost: Forced Singletons

When To Use This Pattern

When NOT To Use It

The Simpler Alternative

Summary

When a Button Should Do More Than Close

The dialog was innocent

The first useful clue: don’t make the dialog smart

D-Day was the easy one

The task dialog was less polite

The callback pattern held up

The button we left alone

Small Flutter details that mattered

The quiet lesson

Why Your Flutter UI Freezes: Understanding Async, Await, Compute & Isolates

The Uncomfortable Truth: Dart Is Single-Threaded

The Biggest Misconception in Flutter Development

So What Does Async-Await Actually Do Well?

The Dart Event Loop (And Why It Matters)

Microtask Queue (High Priority)

Event Queue (Normal Priority)

The JSON Parsing Trap

The Fix: Isolates

compute(): Isolates Without the Ceremony

When compute() Isn't Enough: Persistent Isolates

The Decision Framework

Real-World Example: Crypto Wallet Transaction Feed

Common Myths, Killed

The Mental Model That Fixes Everything

Everything about Stateful & Stateless widgets in Flutter

What Is a Widget, Really?

Stateless Widgets

The const Optimization

Stateful Widgets

The Stateful Lifecycle

createState()

initState()

didChangeDependencies()

build()

setState()

didUpdateWidget()

deactivate()

Mistake 1: Registering Handlers After Calling `add()`

Mistake 2: Using `registerFactory`

Mistake 4: Forgetting `.take(1)`

Mistake 5: Mixing `GetIt` and `context.read`

`compute()`: Isolates Without the Ceremony

When `compute()` Isn't Enough: Persistent Isolates

The `const` Optimization

`createState()`

`initState()`

`didChangeDependencies()`

`build()`

`setState()`

`didUpdateWidget()`

`deactivate()`

`dispose()`

`LocalKey`

`GlobalKey`

The `mounted` Property and Async Safety

Why not just use `takePicture()`?

Why `restartable()`?