DEV Community: Paragon Framework

15 green checks and a stale demo

Paragon Framework — Wed, 05 Aug 2026 14:04:48 +0000

I have a release script with fifteen automated checks. It passed all fifteen. Then I opened my own live demo and the About screen showed the previous version.

Here is what it checks, on the release in question:

PASS  version 1.8.0 consistent (pubspec = CHANGELOG = app About screen)
PASS  public changelog announces v1.8 and marks it Latest
PASS  working tree clean (what you see is what packages)
PASS  no merge-conflict markers in tracked files
PASS  every local link on the sales site resolves
PASS  archive contains no internal-only files
PASS  archive contents are built from the current version (1.8.0)
PASS  the site is up (/ returns 200 and is not a Pages error page)
PASS  all 8 landing-page images load from the live site
PASS  analytics beacon present on every public page

Not one of those was wrong. The version really was consistent. The changelog really was updated. The site really was up.

The demo is a separately compiled build, and my deploy script publishes the marketing site. Nothing built the demo, and nothing looked at what the demo was running.

Every check I own is scar tissue

The "is the site up" check exists because I once took the site offline. The "do the images load" check exists because a deploy deleted every image while the page still returned 200 — a status check alone said "fine" the whole time the logo was a broken icon.

They are all reactions to something that already went wrong. Which makes a fully green run a precise statement about my past mistakes, and silent about everything else:

green  ==  "none of my previous mistakes recurred"
green  !=  "nothing is wrong"

Those feel identical at 1am when you want to ship.

The fix is embarrassingly cheap

Flutter writes a version.json next to the web build, populated from pubspec:

{"app_name":"my_app","version":"1.8.0","build_number":"7"}

It's live, it's public, and it's a couple of hundred bytes. So you can just ask the deployed app what it is:

curl -s https://example.com/app/version.json

The check compares that to the version you think you're shipping:

$live = (New-Object Net.WebClient).DownloadString(
    'https://example.com/app/version.json')
if ($live -match '"version"\s*:\s*"([0-9.]+)"' -and $Matches[1] -ne $pubVer) {
    Fail "live demo runs $($Matches[1]) but you are shipping $pubVer"
}

The message matters as much as the check. Mine spells out the recovery, because forgetting the steps is the bug:

FAIL  live demo at /app/ still runs 1.7.0 but you are shipping 1.8.0.
      Rebuild and redeploy it: flutter build web --base-href /app/,
      inject_beacon.ps1 build/web, then copy into the Pages clone.

Ten minutes of work for a hole that had been open for who knows how many releases.

Then I fixed it in the wrong place

This is the part worth your time, because the first failure is ordinary and this one isn't.

I rebuilt the demo, copied it into the GitHub Pages repo, pushed, watched the live version flip to the new number, and moved on.

Then I ran my deploy script for an unrelated change, and it put the old build back.

The layout is the whole story:

site/            <- source of truth, synced wholesale by the deploy script
  index.html
  app/           <- the published copy of the demo  ** still 1.7.0 **
  admin/

paragon-demo/    <- the GitHub Pages repo
  app/           <- what I fixed by hand          ** now 1.8.0 **

I had fixed the destination while the source still held the previous build. The next deploy faithfully republished the stale one, exactly as designed.

For a few minutes I had a "verified fixed" demo on a countdown to breaking again, and the thing that would break it was my own tooling working correctly.

Four things I took from it

Verify the artifact, not the action. "I deployed the fix" and "the fix is live" are different claims. I had confirmed the first and assumed the second.

Poll, don't peek. My first "it's live now" check passed against a CDN copy that hadn't rebuilt yet. Checking once and believing it is how you confirm a lie:

until curl -s "$URL/version.json" | grep -q '"1.8.0"'; do sleep 5; done

Fix the source, not the copy. If a pipeline generates a destination from a source, editing the destination is an illusion with an expiry date.

Check what the user touches. My pipeline was thorough about inputs: source files, version strings, archive contents, links. It had nothing to say about the compiled thing a stranger clicks, which is the only artifact that actually matters.

I found this the ordinary way, by looking at my own product like a user would, hours after telling myself it was done. Every check on that list was earned the same way. This one just cost less than the others, because I got there before a customer did.

How I Made Features in a Large Flutter App Actually Removable

Paragon Framework — Tue, 04 Aug 2026 12:57:51 +0000

"Just delete the features you don't need" is the easiest thing in the world to write in a README, and the hardest to make true.

I hit this building a Flutter app with six verticals in one codebase — marketplace, ride-hailing, car rentals, social feed, chat, wallet. Deleting one should have been simple. It wasn't, because every feature had tendrils:

a route in the central route table
a tab hardcoded in the app shell
a button on the home screen
a service registered in main()

Remove the feature folder and you get a wall of compile errors from files that have nothing to do with it. Here's what actually worked.

Make three things data instead of code

1. Routes

Each feature exposes its own routes from its own folder:

class WalletModule extends AppModule {
  const WalletModule();

  @override
  String get id => 'wallet';

  @override
  List<GetPage> get pages => [
        GetPage(name: AppRoutes.wallet, page: () => const WalletScreen()),
      ];
}

The app's route table becomes a composition:

static final routes = <GetPage>[
  ..._centralRoutes,
  ...ModuleRegistry.pages,
];

Adding or removing a feature stops being an edit to a shared file. It's one line in a registry.

2. Bottom-navigation tabs

This one surprised me. My app shell imported the feed widget directly:

// before — the always-present shell depends on an optional feature
import '../feed/feed_tab.dart';

The shell ships in every build. That import meant the social feature could never be removed.

So a tab became a small data class that a feature contributes:

class ShellTab {
  final String id;
  final int order;      // core tabs use 10/30/40
  final IconData icon;
  final String labelKey;
  final Widget Function() builder;
}

Social contributes its tab at order 20, slotting between home and alerts without the shell knowing it exists. The shell merges its own tabs with ModuleRegistry.shellTabs and sorts.

3. Entry points

Home screens linked to feature screens with Get.toNamed(...). Named routes are already decoupled — no import needed — but navigating to a route that isn't registered just fails silently.

So the route table answers questions about itself:

static final Set<String> _names = {for (final p in routes) p.name};

static bool hasRoute(String route) => _names.contains(route);

And the UI asks before offering:

if (AppPages.hasRoute(AppRoutes.cart))
  ServiceTile(label: 'Cart', onTap: () => Get.toNamed(AppRoutes.cart)),

A build without the module simply doesn't show the button, instead of showing one that goes nowhere.

Two things I got wrong

Both were embarrassing, and both took one line to fix once I actually looked.

A home layout imported an entire feature to format a date. There was a feedRelativeTime() helper living inside feed_tab.dart, and the home screen used it. That single import made the social feature non-removable. Moving the helper to shared/ removed the dependency completely — it was never real coupling, just misplaced code.

Another layout imported a map controller for two numbers. A static const default latitude and longitude. Same fix.

If you try this on your own codebase, look for these first. A surprising amount of "architectural coupling" is just something sitting in the wrong file.

Navigation is not the same as capability

The subtler bug came later. My checkout screen offered "pay with wallet" unconditionally.

In a build without the wallet module, that option still worked — the service was still registered in main(), the balance was real. There was just no wallet screen to open. A payment method with nowhere to top up.

hasRoute was the wrong question. It answers "can I navigate there?" What I needed was "is this feature in the build?":

ModuleRegistry.isEnabled('wallet')   // is this FEATURE here?
AppPages.hasRoute(AppRoutes.wallet)  // can I navigate there?

Conflating those two is exactly how you ship a payment option you can't support.

This is also why I stopped trying to move shared services into modules. WalletService and CartService are used by several features and stay registered centrally — they're cheap and always resolvable. What must not leak is the UI for a feature that isn't installed.

How I know it works

The part that made this trustworthy isn't the architecture, it's the test.

I remove modules from the registry and rebuild, then assert:

the app still analyzes clean — no dangling references
the route count drops by exactly the number that module owned
the tab bar loses exactly the tabs it contributed
isEnabled reports it absent

Dropping the marketplace module takes the app from 38 routes to 30, removes the Shopping home layout from Settings entirely, and falls back to the all-in-one layout if that's what the user had saved. A storefront home screen with no store is worse than not offering it.

Claims about modularity are cheap. Deleting things and watching the build stay green is not.

What I haven't solved

Repositories live in a shared data/ layer, which is what lets home screens preview any feature. That's a deliberate trade for legibility, but it means deleting a feature folder outright still needs its repository registration removed from main().

Someone on r/FlutterDev suggested an event bus — modules fire events instead of calling each other, and a base module routes them. It's a genuinely better answer for cross-module communication. The trade-off is compile-time safety: you can't see who handles an event, or whether anyone does, and tracing a flow becomes grepping for string keys. For a codebase other people have to read quickly, I'm not sure that's the right trade. Still thinking about it.

This came out of building Paragon, a Flutter template. The demo is open if you want to poke at it — no signup.