DEV Community: Ahmed ElFirgany

Stacked Pull Requests: how I would split a Flutter feature into four reviewable layers

Ahmed ElFirgany — Sun, 02 Aug 2026 08:59:42 +0000

The problem is not the code

I build Flutter apps. A normal feature touches four layers at once.

Models and json parsing
Repository and API client
State management
Screens and widgets

When I ship that as one branch, the pull request is somewhere between 1,000 and 4,000 lines. And then one of two things happens.

Either the reviewer opens 40 files, scrolls for ten minutes, and writes "looks good". That is not a review. That is a signature.

Or the reviewer does the job properly, takes three days, and leaves a comment on the models file. Now every screen above it has to change.

The writing was fast. The review was slow. That is the real bottleneck.

The old workaround

You already know it. Split the work into branches yourself.

git checkout -b feat/booking-models
git checkout -b feat/booking-repo     # branched off models
git checkout -b feat/booking-state    # branched off repo
git checkout -b feat/booking-ui       # branched off state

This works for about one day. Then a reviewer asks for a change in feat/booking-models, and you rebase three branches by hand. Then it happens again. Most people give up and go back to the giant branch.

What stacked pull requests change

On July 30 2026 GitHub put stacked pull requests into public preview.

The idea is small. A stack is an ordered series of pull requests. Each pull request targets the one below it instead of targeting main. Only the bottom one targets main.

PR #4  screens and widgets     -> targets PR #3
PR #3  cubits and state        -> targets PR #2
PR #2  repository and api      -> targets PR #1
PR #1  models and parsing      -> targets main

Because each pull request only contains its own layer, opening PR #3 shows you the state management diff and nothing else. Not the models. Not the widgets.

The Flutter example

Say I am building a booking flow. Here is the same feature, sliced.

PR 1 - models and json parsing. Around 190 lines. Targets main.

class Booking {
  final String id;
  final DateTime startsAt;
  final BookingStatus status;

  const Booking({
    required this.id,
    required this.startsAt,
    required this.status,
  });

  factory Booking.fromJson(Map<String, dynamic> json) => Booking(
        id: json['id'] as String,
        startsAt: DateTime.parse(json['starts_at'] as String),
        status: BookingStatus.values.byName(json['status'] as String),
      );
}

Pure data. A reviewer can check the json keys and the null handling in five minutes.

PR 2 - repository and API client. Around 310 lines. Targets PR 1.

class BookingRepository {
  BookingRepository(this._client);
  final ApiClient _client;

  Future<List<Booking>> fetchUpcoming() async {
    final res = await _client.get('/bookings?filter=upcoming');
    return (res.data as List)
        .map((e) => Booking.fromJson(e as Map<String, dynamic>))
        .toList();
  }
}

Now the backend minded reviewer has something to read. Endpoints, error handling, caching. They do not need to wait for my widgets to exist.

PR 3 - cubits and state. Around 240 lines. Targets PR 2.

class BookingCubit extends Cubit<BookingState> {
  BookingCubit(this._repo) : super(const BookingState.initial());
  final BookingRepository _repo;

  Future<void> load() async {
    emit(const BookingState.loading());
    try {
      emit(BookingState.loaded(await _repo.fetchUpcoming()));
    } catch (e) {
      emit(BookingState.error(e.toString()));
    }
  }
}

This is where most real bugs live. Loading states, race conditions, what happens when the user leaves the screen mid request. It deserves its own focused review, and here it gets one.

PR 4 - screens and widgets. Around 380 lines. Targets PR 3.

The UI layer. The designer or the mobile reviewer looks at spacing, accessibility, and empty states. Nothing else is in the diff.

Same feature. Same total lines. Four reviewers can now work in parallel instead of one reviewer working through everything in sequence.

How you build a stack

Install the extension.

gh extension install github/gh-stack

You can also work with stacks on github.com, in the GitHub mobile app, or with a coding agent through the gh-stack skill.

The manual shape is the same idea you already know. Create a branch and open a pull request for your first layer. Then branch off that, and open the next pull request with the previous branch as its base.

gh pr create --base main                  # PR 1
gh pr create --base feat/booking-models   # PR 2
gh pr create --base feat/booking-repo     # PR 3
gh pr create --base feat/booking-state    # PR 4

The difference is that GitHub now understands this is one stack. Every pull request shows a stack map at the top so a reviewer can see which layer they are looking at and where it sits.

Merging

This is the part that used to hurt, and it is the part that got fixed.

Merge the latest ready pull request and it lands, along with every unmerged layer below it, in one operation.
Or merge only one or more lower layers. The pull requests above stay open and automatically rebase and retarget.

No manual rebase chain. And your existing branch protections and required checks still govern what reaches main, so none of your rules change.

Merge queue support is rolling out progressively over the coming weeks.

When this is worth it

Not every change needs a stack. A bug fix is a bug fix.

It pays off when:

The feature crosses architecture layers, which for mobile is most features
More than one person should review, and they care about different things
The bottom layer is stable and could ship on its own value

It is probably overkill when the whole change is under a couple hundred lines, or when you are the only reviewer anyway.

The actual takeaway

We spend a lot of energy trying to write code faster. AI made that part much faster for a lot of teams, which is exactly why review became the visible bottleneck.

Stacked pull requests do not make you write faster. They make your work reviewable. On a real team that is usually where the days are lost.

If you build mobile apps, I would like to know: what is the biggest pull request anyone has ever asked you to review, and did you actually review it?

Flutter web will not render ★ — and I shipped that to a live game

Ahmed ElFirgany — Sat, 01 Aug 2026 10:43:29 +0000

I spent eight days building a small physics game in Flutter and put it online. Then, before telling anyone about it, I opened the live link and played it like someone who had never seen it.

The first level took one arrow. The tower came down. The win panel slid up and said Level Complete, and under it, where the star rating goes, were three empty rectangles.

It had been like that for two days.

The line

Text(
  '★' * s.stars + '☆' * (3 - s.stars),
  style: const TextStyle(
    color: Cfg.targetColor,
    fontSize: 34,
    letterSpacing: 4,
  ),
),

Three filled stars for a clean clear, fewer as you spend more arrows. It reads fine. It runs fine. On macOS in the simulator it looked exactly like I wanted.

On the web build it was three tofu boxes, because the star is U+2605 and the font the page was drawing with does not have that glyph.

The mute button had the same problem. It was a Text widget holding two speaker emoji. Same result: a small round button with a broken square inside it.

Why this does not show up where you are looking

Flutter web draws text through CanvasKit, using the fonts you bundle plus a fallback set it fetches at runtime. That fallback covers a lot, but it is not a promise about every symbol in Unicode, and when it misses, you get the box. Locally you often never see it, because your desktop or simulator has a system font sitting there with the glyph in it.

Two more reasons it survived:

Tests do not catch it. In a Flutter widget test the default font draws every character as a box already, so a golden test cannot tell a working star from a broken one. There was nothing to fail.

I stopped reading my own UI. By day three the win panel was furniture. I was watching the physics, not the panel.

The fix is boring

Material icons are an icon font that Flutter bundles. They always resolve, on every platform, offline.

Row(
  mainAxisSize: MainAxisSize.min,
  children: [
    for (var i = 0; i < 3; i++)
      Padding(
        padding: const EdgeInsets.symmetric(horizontal: 3),
        child: Icon(
          i < s.stars ? Icons.star_rounded : Icons.star_border_rounded,
          color: Cfg.targetColor,
          size: 38,
        ),
      ),
  ],
),

And the mute button:

Icon(
  s.muted ? Icons.volume_off_rounded : Icons.volume_up_rounded,
  color: Colors.white,
  size: 20,
),

The funny part is that the level select screen in the same game was already doing it the right way, with Icons.star_rounded. Two screens, two authors, eight days apart. Both of them me.

The rule I use now

Never draw UI with a decorative Unicode character or an emoji inside a Text widget. Either use an Icon, or bundle a font you have checked yourself and set fontFamily on that text explicitly. If a character is not in ASCII and it is load bearing for the interface, treat it as an asset, not as text.

A quick way to find them all in your own project:

grep -rn "[^\x00-\x7F]" lib/ --include="*.dart"

That printed seven lines for me. Two of them were bugs, one was an em dash that was fine, and the rest were comments.

The part that is not about fonts

While I was in there playing properly, I also found that the heads up display still said BALLS 3. Two days earlier the ball had become an arrow, with a shaft and a fletching and a bow to fire it from. The counter never got the message. Neither did the title screen, which was still telling people to fling something.

None of this was a physics bug. The Box2D world was correct the whole time. Every one of these lived in the first thirty seconds of the game, which is the only part most people ever see.

I think that is the actual distance between code that works and a product that ships. The engine was right. The experience was not, and no test I could reasonably have written would have told me. The only thing that told me was opening the deployed URL and playing it with my hands.

The game

It is called Topple. A bow and arrow knock down physics game in Flutter, using Flame and flame_forge2d for real Box2D physics. Thirteen levels, three materials: wood, stone that works as a wall, and glass that shatters into shards and lets the arrow through. Nothing about a collapse is animated. Every block has its own mass and friction and finds its own way down.

Play it: https://saqrelfirgany.github.io/topple/

Code and a devlog with one entry per day: https://github.com/saqrelfirgany/topple

If you have a Flutter web build up somewhere, go and open it on a machine that is not yours. I would like to know what you find.

I Built a 3D Game in Flutter — With No Game Engine

Ahmed ElFirgany — Sat, 25 Jul 2026 03:48:47 +0000

Everyone says the same thing: Flutter is for apps, not games.

So I decided to find out where that's actually true — by building a 3D endless runner in Flutter. From scratch. No Unity, no Unreal, no game engine at all. Just Dart and Flutter's own rendering stack.

It runs in your browser right now: ▶️ Play it live (desktop, keyboard controls — A/D to switch lanes, Space to jump).

Here's how it works, and what building it taught me about how far Flutter can actually go.

The stack: Flutter GPU + `flutter_scene`

The whole thing sits on two pieces most Flutter developers have never touched:

Flutter GPU — a low-level rendering API that talks almost directly to the GPU through Impeller (the engine that replaced Skia). This is what makes real-time 3D possible at all.
flutter_scene — a higher-level 3D scene API on top of Flutter GPU. It gives you the building blocks a game needs: a scene graph of nodes, a perspective camera, meshes, and glTF model loading.

You build a tree of nodes, point a camera at it, and render it every frame inside a normal Flutter widget. That last part still surprises me — the 3D world is just a CustomPaint-style surface living inside an otherwise ordinary Flutter app.

Faking an infinite world with a handful of objects

An "endless" runner obviously can't build an endless world — you'd run out of memory in seconds. The trick is object pooling: you keep a small pool of track segments and obstacles, and as they scroll past the camera behind the player, you recycle them back to the front with new positions.

The player never actually moves forward. The world moves toward the player, and a fixed number of segments cycle forever. Same idea for obstacles and coins. It means the game runs at a constant, tiny memory footprint — which is exactly what keeps it smooth on weaker devices.

The parts that were genuinely hard

Collision that feels fair. Detecting a collision is easy. Making it feel right is not. Too strict and the player rages at hits that "clearly missed." Too loose and it feels cheap. Most of the tuning time went into the hit-boxes and the exact frame timing, not the math.

The camera. A perspective camera that follows an endless track has to sell speed and depth without making the player motion-sick. Small changes to field-of-view and follow distance completely change how fast the game feels at the same actual speed.

Swapping the primitive for a real model. The player started life as a literal spinning cube. Importing a real glTF model meant wrestling with scale, orientation, and lighting until it sat in the world correctly instead of floating sideways in the dark.

The bug that flipped the world upside down. One inverted axis, and the entire scene rendered mirrored — obstacles coming from the wrong direction, the track pointing the wrong way. Three hours of staring. The fix was a single line. That's build-in-public for you: I get to show you the wins and the facepalms.

So — is Flutter for games?

For a AAA title? No. That's not what this experiment was about.

But for real-time 3D, running cross-platform (mobile, desktop, and the web build you just played) from a single Dart codebase — it went much further than "Flutter is only for apps" would ever suggest. The fastest way to learn a tool's real limits is to take it somewhere it "isn't meant to go."

I'm building this in public, one increment at a time — collision, scoring, a start menu, a persistent leaderboard, particle effects. The code is all here: github.com/saqrelfirgany/flutter-scene-runner.

If you've pushed Flutter somewhere it "wasn't meant to go," I'd love to hear about it in the comments. And if you want to follow the build, this is part 1 of the series. 👇

Ahmed ElFirgany — Mobile Expert | Flutter · Android Native · iOS Native | Expanding into Backend (PHP · Laravel) | performance & Clean Architecture; building a 3D game in Flutter.

Let's connect:

💼 LinkedIn — linkedin.com/in/ahmed-elfirgany
💻 GitHub — github.com/saqrelfirgany
🎮 Play the game (live) — saqrelfirgany.github.io/flutter-scene-runner
🐦 X — @saqrelfirgany
💬 WhatsApp — wa.me/201025592065
✉️ saqrelfirgany@gmail.com

Offline-First Flutter: How We Built a CRM That Manages 100K+ Leads With No Internet

Ahmed ElFirgany — Sat, 23 May 2026 07:05:51 +0000

Most apps quietly assume the network is always there. Then a real user walks into a basement, a half-built apartment tower, or an elevator — and the app falls apart.

For a real-estate sales agent, that moment isn't a glitch. It's a lost lead, and a lost commission.

When we built the AM Live CRM at Aqarmap (Egypt's largest property platform), our field agents were managing 100,000+ leads a month — and a huge chunk of their day happened exactly in those dead zones: new developments, underground parking, remote plots with one bar of signal.

A "cache the last response" approach wasn't enough. We needed the app to be fully usable with zero connectivity — create a lead, move it through the pipeline, log a call — and have all of it sync cleanly the moment the network came back.

Here's the architecture we landed on, and the mistakes worth avoiding.

The core idea: the local database is the source of truth

The biggest mental shift in offline-first is this: the UI never talks to the network directly. It talks to the local database. The network is just a background process that keeps the local store and the server eventually consistent.

UI / BLoC  ->  Repository  ->  Local DB (SQLite)  <->  Sync engine  <->  API

Every read comes from SQLite. Every write goes to SQLite first, then gets queued for the server. The user never waits on a request, and never sees a spinner that depends on signal.

Pillar 1 — Write locally, queue the intent

When an agent edits a lead, we do two things in one transaction: update the local row, and record the intent to sync it.

class SyncOperation {
  final String id;          // uuid
  final String entity;      // 'lead', 'call_log', ...
  final String entityId;
  final OpType type;        // create | update | delete
  final Map<String, dynamic> payload;
  final int localVersion;   // bumped on every local edit
  final DateTime createdAt;

  const SyncOperation({ /* ... */ });
}

Future<void> updateLead(Lead lead) async {
  await db.transaction((txn) async {
    await txn.update('leads', lead.toMap(),
        where: 'id = ?', whereArgs: [lead.id]);

    await txn.insert('sync_queue',
        SyncOperation(
          id: uuid.v4(),
          entity: 'lead',
          entityId: lead.id,
          type: OpType.update,
          payload: lead.toMap(),
          localVersion: lead.version + 1,
          createdAt: DateTime.now(),
        ).toMap());
  });
}

Because the row and the queue entry are written in the same transaction, you can never end up in a state where the UI shows a change that will never be synced.

Pillar 2 — Drain the queue when connectivity returns

A single listener watches connectivity and kicks off a drain. The drain processes operations in order, one entity at a time, and only removes an operation from the queue after the server confirms it.

connectivity.onStatusChange
    .where((status) => status.isOnline)
    .listen((_) => _syncEngine.drain());

Future<void> drain() async {
  if (_isSyncing) return;          // never run two drains at once
  _isSyncing = true;
  try {
    final ops = await _queue.pending(limit: 50);
    for (final op in ops) {
      final result = await _push(op);
      if (result.isConflict) {
        await _resolveConflict(op, result.serverState);
      }
      await _queue.remove(op.id);   // only after success
    }
  } finally {
    _isSyncing = false;
  }
}

Two details that saved us a lot of pain:

A guard flag (_isSyncing) so a flaky connection toggling on/off doesn't spawn overlapping syncs that duplicate writes.
Remove-after-confirm. If the app dies mid-sync, the operation is still in the queue and simply replays next time. Idempotent server endpoints (keyed by the operation id) make replays safe.

Pillar 3 — Resolve conflicts on purpose, not by accident

The dangerous case: an agent edits a lead offline while a colleague edits the same lead on the server. If you blindly push, you silently overwrite their work.

We versioned every record. When the server reports a newer version than the one our operation was based on, we don't guess — we run an explicit strategy:

Future<void> _resolveConflict(SyncOperation op, Lead serverState) async {
  // Field-level merge: keep the server's pipeline stage (authoritative,
  // it drives reporting), keep our locally-edited contact notes.
  final merged = serverState.copyWith(
    notes: op.payload['notes'],
    updatedAt: DateTime.now(),
  );
  await leadRepo.upsertLocal(merged);
  await _queue.enqueueUpdate(merged); // push the merged result back
}

For some fields last-write-wins is fine. For others (like the 5-stage pipeline that feeds management reporting) the server stays authoritative. The point is that the rule is a decision you document, not an emergent behavior you discover in production.

What this bought us

Agents stopped losing leads to "no internet." The pipeline kept moving online or off.
The UI got faster, because reads never blocked on the network.
Sync failures became boring: they just retried.

Lessons I'd pass on

Decide offline-first on day one. Retrofitting it onto a network-coupled app is a rewrite, not a feature.
Make the server idempotent before you trust replays. Operation IDs are your friend.
Test on real cellular, not office WiFi. The demo that works at your desk is not the product.
Write the conflict rules down. Future-you will not remember why stage changes behave differently from notes.

I'm Ahmed (Saqr), a senior Flutter engineer — 22+ production apps, 200K+ users. I write about building mobile apps that actually ship and scale.

If this was useful, follow me here and on GitHub, where I maintain an open-source Flutter Enterprise Template used by 100+ developers.

What's your approach to offline sync in Flutter? I'd love to hear it in the comments.