DEV Community: Gulshan Yadav

Building a Responsive Flutter UI That Never Breaks

Gulshan Yadav — Mon, 31 Aug 2026 13:30:00 +0000

LayoutBuilder, breakpoints, and adaptive widgets — a system that survives every screen size, including the ones you didn't test.

The first Flutter app I shipped looked perfect — in the Android Studio emulator, at one fixed resolution. The first person to install it on a real phone had a narrow device, and half the dashboard overflowed with the classic yellow-and-black striped error bars. I fixed that bug, and then the next overflow, and the next, every time someone rotated the screen or resized the window.

So, in this article, I will be showing you how I build responsive Flutter UIs now — the ones that do not break on any screen, orientation, or text scale, because I stopped guessing sizes and started building a small, boring system.

The good news first: you need zero extra dependencies. Responsiveness in Flutter is built into the framework. What you need is the discipline to use the right tools in the right places. Let me show you exactly which tools, in order.

The Rule: Let Constraints Drive, Never Absolute Pixels

The single habit that fixes most breakage: stop using absolute sizes for anything that can vary. No SizedBox(width: 400), no hard-coded card widths, no fontSize: 20 on body text that needs to scale with the user's accessibility settings. If a size depends on the screen, the screen should decide — and Flutter gives you exactly three ways to let it.

Step 1: LayoutBuilder — Size Comes From Your Parent

LayoutBuilder gives you the constraints your parent actually imposes, at build time. This is the workhorse of responsive layout. Here is the breakpoint switch I use in almost every screen:

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

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        final width = constraints.maxWidth;

        if (width >= 1200) {
          return const WideLayout();      // desktop
        } else if (width >= 700) {
          return const MediumLayout();    // tablet / landscape
        } else {
          return const NarrowLayout();    // phone
        }
      },
    );
  }
}

Three layouts, one decision point. When you open this file, you can see the whole responsive story of the screen at a glance. The breakpoints (1200 / 700) are not magic numbers — they are where your layout actually stops working, and you should tune them to your design, not to a blog post.

Inside a layout, use the same pattern at a finer grain. A detail panel that should sit beside content on wide screens and below it on narrow ones:

LayoutBuilder(
  builder: (context, constraints) {
    final showSidebar = constraints.maxWidth >= 900;
    return Row(
      children: [
        Expanded(child: content),
        if (showSidebar) SizedBox(width: 320, child: sidebar),
      ],
    );
  },
)

Step 2: Flexible and Expanded — Sharing Space, Not Fighting Over It

Half the overflows I debugged came from fixed-size children inside flexible parents. Expanded and Flexible are how you tell a child, "take the space the parent decided to give you, and make it work." The rule I live by: a Row or Column of dynamic content should have exactly one child that can't be squeezed — and the rest should be flexible.

The distinction between the two matters more than people think. Expanded is a Flexible with fit: FlexFit.tight — the child must fill the assigned space, even if that means being stretched past its natural size. Flexible with FlexFit.loose gives the child the space as an upper bound: it can take less if it does not need more. For a title row you almost always want Flexible on the text side and Expanded only when you genuinely need the child to fill every pixel. Text widgets also get an explicit flex factor when you want them to share proportionally — a Flexible(flex: 2) and a Flexible(flex: 1) split leftover space 2:1, which is how I do two-column info rows without any fixed widths.

Row(
  children: [
    const CircleAvatar(radius: 24),
    const SizedBox(width: 12),
    Expanded(
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(title, maxLines: 1, overflow: TextOverflow.ellipsis),
          Text(subtitle, maxLines: 2, overflow: TextOverflow.ellipsis),
        ],
      ),
    ),
    if (trailing != null) trailing!,
  ],
)

Notice the details that keep this from breaking: the titles are capped with maxLines and TextOverflow.ellipsis, so a long name or a large font scale cannot push the row out of bounds. Expanded takes the remaining width; the trailing widget keeps its natural size. If you leave every child unconstrained and just hope, the text will win and the row will break.

For grids and lists, the same idea: GridView with SliverGridDelegateWithMaxCrossAxisExtent lets the number of columns be decided by available width instead of by you:

GridView.builder(
  gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent(
    maxCrossAxisExtent: 260,
    childAspectRatio: 1.2,
  ),
  itemBuilder: (context, index) => ProductCard(index: index),
)

On a phone you get 2 columns, on a tablet 4, on a desktop 6 — and you wrote one line. The framework counts columns for you.

Step 3: MediaQuery — The App-Level Facts

LayoutBuilder tells you about space. MediaQuery tells you about the device — orientation, text scale, platform, and safe areas. Use it for decisions that are about the environment, not the box:

final mq = MediaQuery.of(context);

if (mq.orientation == Orientation.landscape && mq.size.height < 500) {
  return const LandscapeCompact();   // desktop-style layout on a phone turned sideways
}

And the one I add to every scaffold: SafeArea. The modern phone cutout, the home indicator, and the notch will eat your content on real devices even though the emulator never shows them. Wrap anything that can sit near the edge:

return SafeArea(child: Scaffold(body: content));

For the orientation decision specifically, OrientationBuilder is sometimes the cleaner tool than reading MediaQuery — it rebuilds exactly when the orientation flips, rather than on every size change, which keeps it cheap:

OrientationBuilder(
  builder: (context, orientation) {
    if (orientation == Orientation.portrait) {
      return const Column(children: [SettingsList(), Controls()]);
    }
    return const Row(children: [Expanded(child: SettingsList()), Controls()]);
  },
)

Use OrientationBuilder when your layout decision is literally "portrait vs landscape." Use LayoutBuilder when the actual width or height numbers matter. The two overlap, but they answer different questions, and mixing them thoughtfully is what separates a responsive app from a fragile one.

Step 4: Adaptive Widgets — Same Logic, Different Widget

Responsive is not just about size; it is about choosing the right widget for the platform and context. Flutter's material library gives you widgets that pick for you. SelectableRegion aside, the ones I reach for daily:

NavigationRail vs NavigationBar — a rail on wide screens, a bottom bar on phones. The adaptive variants handle the switch.
Dialog vs AlertDialog — trivial, but the adaptive dialog picks the platform style.
ListView vs Wrap — when item counts are unknown, a Wrap flows instead of overflowing.

Here is the pattern I actually ship — a single AdaptiveProductGrid that switches layout based on width using only core widgets:

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

  @override
  Widget build(BuildContext context) {
    return LayoutBuilder(
      builder: (context, constraints) {
        final isWide = constraints.maxWidth >= 700;

        return Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text('Featured',
                style: isWide
                    ? Theme.of(context).textTheme.headlineMedium
                    : Theme.of(context).textTheme.titleLarge),
            if (isWide)
              Row(
                children: [
                  Expanded(child: _Card()),
                  const SizedBox(width: 16),
                  Expanded(child: _Card()),
                  const SizedBox(width: 16),
                  Expanded(child: _Card()),
                ],
              )
            else
              ListView.separated(
                shrinkWrap: true,
                physics: const NeverScrollableScrollPhysics(),
                itemCount: 3,
                separatorBuilder: (_, __) => const SizedBox(height: 12),
                itemBuilder: (_, i) => _Card(),
              ),
          ],
        );
      },
    );
  }
}

One screen, two arrangements, driven entirely by the parent's constraints. This is the whole method.

Important Notes and Pitfalls

These are the traps I hit so you do not have to:

MediaQuery.of(context) used for layout decisions deep in the tree is fine, but for per-widget sizing always prefer LayoutBuilder — the media query tells you about the whole screen, not the space your widget actually has inside a column.
Hard-coded heights still break everything. If a card has height: 240 and the text inside scales up for an accessibility setting, you get overflow. Use IntrinsicHeight sparingly (it is expensive) or let content define height with flex containers.
Rotating the phone is a different layout pass. Test landscape — a phone rotated is narrower in height than a desktop, and a wide row that worked in portrait will overflow in landscape.
Text scaling is the silent killer. Users with large font settings will break your carefully measured UI even though every widget is "flexible." Always cap text with maxLines + overflow, and never hard-code fontSize on text that must scale — use MediaQuery.textScaler or the theme.
Sizes inside an Expanded are still fixed. Expanded gives the child a width, but the child can still overflow vertically if you set a fixed height and the content is taller. The pair that works is flex on the axis you want to survive and clip/scroll on the other.
Test on the smallest device you plan to support, not the prettiest. If the breakpoint logic is right, the small phone is where it proves itself.

The Questions I Get Every Time

"Do I need a package like responsive_framework?" No. For 90% of apps, the core toolkit above is enough, and every package you add is a constraint you will fight later. Packages help when you want media-query-style breakpoint helpers across a huge app; by the time you need that, you also know exactly why, and you can evaluate them on their merits. Start dependency-free.

"Where should the breakpoint numbers live?" One constants file. Put 1200, 900, 700 in named constants like kTabletBreakpoint and kDesktopBreakpoint, with a comment explaining what breaks at each width. Magic numbers scattered across 40 widgets are how "we tuned it once" becomes "we tuned it forty times, inconsistently."

"What about very wide desktop windows?" Cap the content, do not stretch it. A ConstrainedBox with maxWidth: 1200 centered on screen reads far better than a dashboard that spans 2,500 pixels of ultrawide. Wider is not better past the point where the eye has to travel too far.

"How do I handle tablets with weird aspect ratios?" Same as everything else — by width, not by device model. Foldables, split-screen multitasking, and desktop windows all produce arbitrary widths, and a width-driven layout handles all of them with the same three branches.

The Method, Compressed

Here is the decision rule I hand to anyone on my team, in order of preference:

Let the parent decide. LayoutBuilder at the top of the screen; choose a layout from the available width.
Never fight the space. Expanded / Flexible for the dynamic content; cap text with maxLines and ellipsis.
Ask the device for facts. MediaQuery for orientation and text scale; SafeArea for real-device edges.
Let the framework count. SliverGridDelegateWithMaxCrossAxisExtent and adaptive material widgets instead of manual math.
Prove it. Run the screen at every breakpoint width, both orientations, and the largest text scale your OS offers — that ten-minute pass catches the regressions.

Done that way, "responsive" stops being a heroic refactor and becomes the default. No overflows, no fixed-size assumptions, no surprises when someone installs the app on a phone you never owned.

I have also written about adaptive navigation and platform-adaptive theming — comment below with your own responsive horror story, or the screen that keeps breaking for you, and I will cover it next.

*Gulshan Yad

Running LLMs Without a GPU: What's Actually Possible

Gulshan Yadav — Mon, 31 Aug 2026 02:30:00 +0000

The honest numbers on CPU, NPU, and iGPU inference — what runs, how fast, and when to stop pretending.

Last year a friend who runs a small consulting firm in Dubai asked me what GPU he needed to "run AI locally." He had a budget in mind and had already been quoted a four-figure price tag for a workstation. I asked him what he actually wanted to run. A document chatbot over his firm's contracts. He owned a three-year-old office laptop with 16 GB of RAM and no discrete GPU.

I told him not to buy anything yet. Two hours later, I had a 7B-parameter model running on that laptop at about 11 tokens per second, answering questions from his own PDFs. Not fast enough for a chat product serving a thousand users. Fast enough for a private assistant that costs nothing per query and keeps every contract on his machine.

The market wants you to believe local AI requires expensive hardware. The truth is more interesting and much cheaper. Here is what is actually possible — with real numbers, real architecture, and an honest map of where CPU-only inference stops being viable.

Why Everyone Thinks You Need a GPU

The confusion comes from a conflation of two different workloads. Training and fine-tuning a model is brutally compute-hungry: it means doing forward passes over billions of parameters millions of times, and backpropagation on top. That genuinely wants GPUs, and a lot of them.

Inference — running the model to produce an answer — is a different animal. Generating one token means one forward pass through the network. It is memory-bandwidth bound far more than compute bound, especially at the small batch sizes a single user generates. That is the single most important fact in this entire article: for single-user inference, what matters is how fast you can stream weights from memory, not how many FLOPS you have. A CPU with lots of fast RAM can do a surprisingly respectable job, and modern processors have neural accelerators that help even more.

What Runs, and How Fast: The Honest Numbers

Here are the real token rates I have measured on actual hardware, not the marketing ones. Your mileage varies, but these are the right ballparks for current consumer machines:

Setup	Model & quantization	Memory	Speed
2021 office laptop, 16 GB RAM	Llama-3.1-8B, Q4_K_M	~5 GB	~10–12 tok/s
Apple M2/M3 (MacBook Air)	Llama-3.1-8B, Q4_K_M	~5 GB	~25–35 tok/s
Apple M2 Pro/Max (memory bandwidth)	14B, Q4_K_M	~9 GB	~20–30 tok/s
Recent laptop CPU with NPU (Intel/AMD/Qualcomm)	7–8B, Q4, NPU offload	~5 GB	15–30 tok/s, lower power
DDR5 desktop CPU (16 cores, no GPU)	8B, Q4_K_M	~5 GB	15–20 tok/s
Same desktop, 32 GB RAM	14B Q4_K_M	~9 GB	8–12 tok/s
iGPU (shared memory) offload	8B, Q4_K_M	~5 GB	modest gain over CPU alone

For context: comfortable reading speed is roughly 20 tokens per second. Below 8 tokens per second, interactive chat starts to feel sluggish, though a batch job — summarize these 400 documents overnight — does not care about interactivity at all, which changes the calculus completely.

One more distinction that explains why CPU inference feels uneven in practice: the two phases of generation behave very differently. Prompt processing (reading the input, aka prefill) is compute-bound and can be slow on CPU for long inputs — a 2,000-token prompt might take a second or two before the first output token appears. Token generation (decode) is memory-bandwidth-bound and steady — once the model is warmed up, each output token streams at a consistent rate. So the experienced quality of a CPU model is dominated by prompt length: short prompts with long answers feel fine; long prompts with short answers feel sluggish, and that is pure prefill time, not generation speed. Capping context and keeping inputs tight is not a quality compromise, it is a latency lever.

The magic ingredient on the Apple side is unified memory: the same memory serves CPU and GPU, and it is fast memory. That is why a fanless MacBook Air outperforms a bigger Windows laptop for llama.cpp. On the Windows/Intel side, the NPUs shipping in 2024+ laptops are the emerging story — they are built for low-power token generation, and software support is maturing quickly.

The Stack That Makes This Work

Every serious CPU inference setup is built from the same four pieces:

1. Quantized models (GGUF). The breakthrough that made CPU inference practical. You take a model whose weights are 16-bit floats and shrink them to 4-bit integers, trading a little quality for a ~4x memory and bandwidth reduction. The GGUF format (from the llama.cpp project) is the standard container. The Q4_K_M variant is the sweet spot I default to — decent quality, ~5 GB for an 8B model, fits in a laptop's budget. Q8_0 is better quality at ~9 GB; Q3_K_M fits in 4 GB but you will feel the quality loss.

2. llama.cpp. The reference runtime. A pure C/C++ implementation that runs on CPU, and offloads layers to GPU/NPU where available. It is the engine behind virtually every local-LLM tool you have heard of, and it is fast on CPU because it was written to be.

3. A server layer. llama.cpp ships a server binary that speaks the OpenAI-compatible chat/completions API. This is the detail that makes CPU inference actually usable: any tool that talks to the OpenAI API — including your existing app, if you point its base_url at your local server — will work against your CPU model with a one-line change.

4. Ollama (or llama-cpp-python) for the glue. Ollama wraps llama.cpp with model management and a dead-simple CLI; llama-cpp-python gives you the same engine as a Python package. Both are legitimate; you are choosing convenience over control.

Let's Actually Run One

Here is the whole setup on a Mac or Linux box. First, install Ollama and pull a quantized model:

# install ollama, then:
ollama pull llama3.1:8b-q4_K_M
ollama serve

That single command is now a running LLM endpoint on http://localhost:11434, OpenAI-compatible. Test it:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.1:8b-q4_K_M",
       "messages": [{"role": "user", "content": "Explain quantization in 50 words."}]}'

If you prefer raw llama.cpp for control — say, you want to offload specific layers to an iGPU or NPU — you clone it and run the server directly:

git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
  -m llama-3.1-8b-instruct-Q4_K_M.gguf \
  --n-gpu-layers 12 \
  -c 4096

The --n-gpu-layers flag is the whole game on hybrid hardware: you push the layers that benefit from the GPU/NPU and keep the rest on CPU, trading power draw for speed. On the Apple side the equivalent is Metal layers (-ngl with Metal enabled).

Now the part people forget. Point your OpenAI-compatible client at it:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="llama3.1:8b-q4_K_M",
    messages=[{"role": "user", "content": "Summarize the attached contract risk clauses."}],
)
print(resp.choices[0].message.content)

That is it. Your app now runs on a local model with zero per-query cost and zero data leaving the machine. The entire "I need a GPU" story collapses into one base_url change.

If you do not know which model to start with, here is the shortlist I use. For a first experiment, a 7–8B model at Q4_K_M (Llama 3.1, Qwen 2.5, Gemma) is the right default on 16 GB of RAM — big enough to feel genuinely capable, small enough to be usable. If you are on 8 GB or an older machine, step down to a 3–4B model at Q4_K_M; the quality gap is smaller than the speed gap suggests. And if you only need classification or extraction, a 1–3B model at 40+ tok/s will beat an 8B at 10 tok/s for the job. The rule: pick the smallest model that passes your acceptance test, then measure — most people overestimate what they need by one size.

What Makes CPU Inference Go Fast (or Slow)

If you are on CPU-only and the speed is not acceptable, the fix is almost never "get a GPU." Work through this order:

Check your quantization. Going from Q8_0 to Q4_K_M nearly doubles throughput at modest quality cost. For chat, most people cannot reliably tell the difference.
Cap your context. A long conversation balloons the prompt-processing phase. Dropping -c from 8192 to 4096 makes the first token arrive much faster.
Use your accelerators. Offload layers to the iGPU/NPU where available. Even a partial offload cuts power draw and wall time.
Match the model to the job. A 3B model at 40 tok/s is better than an 8B at 9 tok/s for classification, extraction, or summarization. Use a small model for the routine work and escalate only when needed.
Cache. KV-cache reuse and prompt caching cut latency dramatically on repeated queries. llama.cpp supports both.

And here is the counterintuitive one: for batch work, a slow model is a non-issue. If you need to tag 10,000 support tickets overnight, 5 tok/s is plenty. You are optimizing for throughput over time, not first-token latency, and CPU inference wins that comparison on cost by a mile.

The same logic extends to embeddings, which people forget entirely. An embedding model like a small 300M–1B parameter encoder runs happily on CPU and is the backbone of local RAG: it turns your documents into vectors on your own machine, with no API calls and no data leaving the building. I have run a full local retrieval pipeline — embeddings plus a small chat model — on a single 16 GB laptop, and the retrieval step, which is the part that actually makes answers good, is nearly instant. If your goal is a private document assistant, the LLM is the part you have to accept as "good enough"; the embeddings are the part that genuinely shines.

Where It Breaks: The Honest Limits

I want to be equally honest about the wall. CPU-only inference fails in four specific places, and you should not pretend otherwise:

Large models. Anything above ~14B at Q4 needs 10+ GB just for weights, and you will hit 5–8 tok/s — below the interactive threshold. Models that need 32 GB of RAM are off the table entirely on consumer hardware.
High concurrency. A CPU serving five users at once just divides its tokens between them. This is a single-user story, or a low-concurrency internal tool, not a public product.
Long-generation tasks. Drafting a full article or a 2,000-token email response is painful at 10 tok/s — 3+ minutes. Plan for it or use a small, fast model for drafting.
Agent workloads. When an agent runs ten chained model calls with tool calls in between, each one pays the full prompt-processing tax. On CPU, a five-step agent run can take minutes. Local-first agents on CPU exist, but you are optimizing for privacy and cost, not speed.

When You Actually Do Need a GPU

You need the GPU when the workload is compute-bound or concurrent: fine-tuning, large-scale embedding jobs, or serving many simultaneous users. If you are building the next consumer chatbot product, you are not the CPU story. You are the cloud API story.

But here is the framing I use now, after years of building: the GPU question is not "should I buy one" — it is "what is the workload, what is the concurrency, and what are the latency requirements?" A private document assistant, a code-completion tool running on a single developer's machine, an on-prem compliance filter that must never see the internet, a batch tagging pipeline — all of these are CPU-viable today, and the hardware you already own is probably enough to start.

The Practitioner's Checklist

When someone asks me to stand up local LLMs on the hardware they have, I work through this list:

[ ] Define the workload: interactive chat, batch processing, or agent loops
[ ] Measure RAM: weights (Q4 ≈ 0.6–0.7 GB per billion params) plus context, plus OS
[ ] Pick GGUF quantization: Q4_K_M default, Q8_0 if quality matters more than speed
[ ] Start with the biggest model that fits in RAM at the target speed; drop a size if under ~8 tok/s for chat
[ ] Set the server up OpenAI-compatible so existing code works with a base_url change
[ ] Cap context to what the task actually needs
[ ] Offload layers to iGPU/NPU/Metal where available
[ ] For batch jobs, accept low token rates and let throughput win
[ ] For agents, budget for multi-call latency or drop to a smaller model
[ ] Keep a cloud API as the escape hatch for the jobs that outgrow the box

The Real Answer

My friend in Dubai runs his contract assistant on that same laptop today. It does not write poetry and it is not answering a thousand concurrent users. It reads contracts, answers questions in context, and costs him nothing per query — and his documents never leave his machine. That is the actual value proposition of CPU inference: not "local models beat the cloud," but "local models are good enough for a specific class of work, and that class is much bigger than people think."

Start with what you already own. Quantize, cap context, offload what you can, and match the model to the job. You will be surprised how far a laptop goes — and you will only spend GPU money when the workload genuinely demands it.

*Gulshan Yad

Flutter Provider vs Riverpod vs Bloc — Which Should You Learn?

Gulshan Yadav — Sun, 30 Aug 2026 13:30:00 +0000

The question every Flutter developer asks, answered with a framework instead of a fanboy answer.

I get the same question at least twice a month, in comments, in DMs, from junior devs at meetups: "Provider, Riverpod, or Bloc — which one should I learn?" It is the Flutter equivalent of asking which framework to learn first in JavaScript, and the answer is usually whoever answered last. That is not how I answer it anymore, because I have shipped Flutter apps with all three — some for clients, some for my own products — and each one of them was the right choice in a different context.

Here is the honest version. Not the version where the latest package wins because it is newer. The version where I tell you exactly what each solution costs you and when it pays for itself.

Why This Question Is Hard to Answer

State management is the first real architectural decision a Flutter developer makes, and the ecosystem makes it harder than it needs to be. All three of these solutions work. All three are actively maintained, documented, and power real production apps. You will not ship a broken app because you picked Provider over Bloc.

So the real question is not "which is best" — it is "which should you learn first, and which should you use, given what you are building and who will maintain it." Those are different answers, and conflating them is where developers waste months. I spent a year on the wrong answer myself, so let me save you the detour.

The Criteria

Before the comparison, here are the six criteria I actually judge state management on when I recommend it to a client or a mentee. They are ranked in the order they bite you in production:

Criterion	What it really means
Learning curve	Days until a new dev can ship a feature, not a demo
Boilerplate	Lines of code per feature — and lines you can't avoid
Testability	How easy it is to test business logic without a widget tree
Ecosystem & tooling	DevTools support, community packages, debugging experience
Refactor cost	What it costs to migrate away if you outgrow it
Team fit	How readable it is to the people who will maintain it

Now let me score each solution against those, honestly.

Provider — The Gateway Drug, and Proud of It

Provider is what most Flutter developers learn first, because it is what the official docs steered you toward for years. It is a thin wrapper over InheritedWidget, and that is its superpower: it does one thing, and it does it well. You expose a value to the widget tree with Provider.of or Consumer, and widgets rebuild when that value changes.

The code is refreshingly small:

class CartProvider extends ChangeNotifier {
  final List<CartItem> _items = [];
  List<CartItem> get items => List.unmodifiable(_items);

  void add(CartItem item) => _items.add(item);
}

// expose it
ChangeNotifierProvider(
  create: (_) => CartProvider(),
  child: const MyApp(),
)

// consume it
final cart = context.watch<CartProvider>();

The strengths are real. There is almost no ceremony: no events, no states, no generators. A junior developer can read Provider code the afternoon they learn it, which makes it an excellent default for small-to-medium apps and for teams that do not want to hire around a paradigm. The DevTools integration is solid, and Provider's companion packages (ChangeNotifierProvider, MultiProvider, ProxyProvider) cover most needs without pulling in anything heavy.

The weaknesses are the flip side of the simplicity. Because the model combines state and notification, logic and presentation get tangled fast as the app grows. There is no enforced structure — nothing stops you from calling notifyListeners from a widget, and nothing stops you from reaching into another part of the tree with a god-object provider. Dependency ordering between providers is implicit and can get genuinely confusing at scale. And testing means either mounting widgets or mocking providers, which is more ceremony than the two alternatives.

Score: learning curve 5/5, boilerplate 5/5, testability 3/5, ecosystem 4/5, refactor cost 3/5, team fit 4/5.

Riverpod — The Same Idea, Grown Up

Riverpod is what Provider became when the author took the lessons learned from the original and started over. Same mental model — read a value from the tree, get a rebuild when it changes — but with the weak spots engineered out. Providers are now top-level functions, which means they can be created, composed, and tested without a widget tree at all.

final cartProvider = NotifierProvider<CartNotifier, List<CartItem>>(CartNotifier.new);

class CartNotifier extends Notifier<List<CartItem>> {
  @override
  List<CartItem> build() => [];

  void add(CartItem item) => state = [...state, item];
}

// in a widget
final cart = ref.watch(cartProvider);

The gains over Provider are measurable. Testability is dramatically better because you can build a ProviderContainer in a plain Dart test and exercise providers directly. Dependency injection between providers is explicit — a provider can declare its dependencies by reading another provider, and the compiler catches mismatches. The DevTools integration (via the Riverpod extension) is excellent, with a state inspector that shows you the whole provider graph live.

The costs: Riverpod adds a new vocabulary — Notifier, StateProvider, FutureProvider, StreamProvider, ref.watch vs ref.listen — and that vocabulary is the real learning curve. It is not that any one concept is hard; it is that there are many concepts, and beginners reach for the wrong provider type constantly. The refactoring cost also bites: because Riverpod is more opinionated, migrating a codebase to it is closer to a rewrite than a rename. If you learn it first, great. If you are coming from Provider, the migration of a large app is a real project.

Score: learning curve 3/5, boilerplate 4/5, testability 5/5, ecosystem 4/5, refactor cost 3/5, team fit 4/5.

Bloc — Structure With Teeth

Bloc is the most opinionated of the three, and it wears that as a badge. The idea: state lives in Bloc classes that receive Events and emit States, strictly one way. UI sends events; the bloc processes them and emits a new state; the UI rebuilds off the state. No widgets ever mutate state, and no state ever mutates widgets.

sealed class CartEvent {}
class AddItem extends CartEvent {
  AddItem(this.item);
  final CartItem item;
}

sealed class CartState {}
class CartLoaded extends CartState {
  CartLoaded(this.items);
  final List<CartItem> items;
}

class CartBloc extends Bloc<CartEvent, CartState> {
  CartBloc() : super(const CartLoaded([])) {
    on<AddItem>((event, emit) {
      final current = (state as CartLoaded).items;
      emit(CartLoaded([...current, event.item]));
    });
  }
}

Where Bloc wins is scale and team discipline. The explicit Event → State contract makes flows auditable: you can read a bloc and see exactly what every user action can do. It is the easiest of the three to test in isolation — a bloc is plain Dart, no widget tree, so unit tests are straightforward and the bloc_test package makes them nearly declarative. For a team of ten shipping a complex app, the ceremony is a feature, not a tax: it keeps everyone writing the same shape of code.

Where Bloc costs you is up front. The boilerplate is real — events, states, and a bloc class for every feature, plus generated code if you go all in on the builder packages. Beginners drown in it, because the pattern has to be internalized before the code becomes readable. Debugging also has a rhythm you have to learn: you do not just read variables, you read event/state transitions in the bloc DevTools extension. It is the steepest curve of the three, and it only pays off if your app is complex enough to need the guardrails.

Score: learning curve 2/5, boilerplate 2/5, testability 5/5, ecosystem 5/5, refactor cost 3/5, team fit 3/5.

The Honest Comparison Table

Criterion	Provider	Riverpod	Bloc
Learning curve	5/5	3/5	2/5
Boilerplate (less is better)	5/5	4/5	2/5
Testability	3/5	5/5	5/5
Ecosystem & tooling	4/5	4/5	5/5
Refactor cost (higher is worse)	3/5	3/5	3/5
Team fit at scale	3/5	4/5	5/5

None of them is broken. What the table shows is that they optimize for different stages of the same journey, and that is the real insight.

What This Looks Like in a Career

Here is the pattern I have watched play out with dozens of developers, including myself. You learn Provider first because it is the smallest thing that works. You ship an app or three, and you hit the wall where the app is big enough that Provider's lack of structure makes the codebase hard to change without breaking things. Somewhere in there you discover Riverpod, and it feels like Provider with the training wheels off and the safety rails on — same mental model, real structure, and you can test it without a widget tree.

Bloc is the destination for the people who need the discipline, the ones who land on large teams or complex products where consistency across ten developers matters more than how fast one developer can type. If you spend your career building solo apps, you may never need it.

The Decision Rule

So, back to the question. Here is the framework I actually give people, in order of priority:

If you have never shipped a Flutter app: learn Provider first. It is the smallest possible surface. Build two or three real apps with it. The concepts — inherited widgets, rebuilding on change, scoping — carry over to everything else.
If you are building a serious app that you will maintain for a year or more, solo or with one or two people: use Riverpod. It gives you testability and composition at a fraction of Bloc's ceremony, and it is where the ecosystem's energy is going.
If you are on a team, or building something with genuinely complex flow (auth, onboarding, multi-role permissions): use Bloc. The structure is the point. Let the boilerplate be the price of ten people agreeing on one shape.
Never start a project with Bloc because it is "more powerful." Power you do not need is just tax. Start small, and let the complexity of your app, not the hype of a package, move you up the ladder.

And one rule that outranks all of them: whatever you pick, do not spread state management across two solutions in the same app. I have inherited codebases that mixed Provider and Bloc because a team "was migrating." That is the worst option on this list — worse than any of the three done consistently. Pick one, use it everywhere, and spend your time on features.

The good news is that this is a two-week decision, not a two-year one. The concepts transfer. Learn Provider, ship something, and by the time you genuinely need more structure, you will know it — because your own codebase will tell you, the same way mine told me.

*Gulshan Yad

LLM Observability: Tracing, Logging, Debugging Agent Runs

Gulshan Yadav — Sun, 30 Aug 2026 02:30:00 +0000

Why your LLM app will fail silently, and how to see it before your customers do.

Three weeks. That is how long a customer-support agent shipped confidently wrong answers for a logistics client I work with before anyone noticed. The agent's job was simple: look up a shipment's status and reply to the customer. It did this hundreds of times a day. Every request returned HTTP 200. Latency was fine. The API bill looked normal. And the agent was quietly hallucinating tracking numbers.

The first clue came from a phone call. A customer in Jeddah had been told her package was "delivered" — it was not. We pulled the logs. There were logs. They said: request received, model called, response returned, 200 OK. Nothing else. No record of what the retrieval step actually returned, no record of what the prompt looked like that day, no record of which model version answered, no record of how many tokens it burned to be wrong.

That is the moment I stopped thinking about LLM observability as a nice-to-have and started treating it as the difference between a working system and an expensive black box. In this article I am going to walk you through everything I now do — and you should too — to trace, log, and debug LLM and agent runs in production.

Why LLM Observability Is Not Regular Observability

Traditional observability assumes your code is deterministic. You log an error, you see the stack trace, you find the bug, you fix it. An LLM breaks that assumption in four specific ways, and each one changes what "observable" means:

The output is nondeterministic. The same prompt can produce a correct answer at 9:00 AM and a hallucination at 9:15 AM with no code change in between. The system did not crash; it drifted. Your logs have to capture state, not just errors.
The hidden state is the whole story. For a normal API you care about the request and response. For an LLM you also care about what was inside the prompt — the retrieved chunks, the tool outputs, the system instructions, the model version. That is where wrongness hides.
Cost is per-token, and it compounds. A retry loop, a bloated context, or a greedy agent can quietly multiply your bill 10x without throwing a single exception. You need token counts, not just request counts.
The failure is often fluent. LLMs fail with perfect grammar and total confidence. Nobody files a bug report for a plausible wrong answer. Your logs are the only witness.

This is why "we log everything with our regular logging library" is not enough. You need tracing that reconstructs the chain of decisions, not a flat list of calls.

The Three Pillars: Tracing, Logging, and Evals

When I design observability for an LLM system now, I build three layers, and they answer three different questions:

Tracing answers "what happened, in what order, and how long did each step take?" A trace is a tree of spans. The root span is the request; child spans are retrieval, prompt assembly, each LLM call, each tool call. Every span carries duration, token counts, cost, model name, and the input/output that passed through it. This is what reconstructs the Jeddah incident — you can see the retrieval returned an empty chunk, the prompt went out truncated, and the model answered anyway.

Logging answers "what does this record look like for later analysis?" I log the full prompt and completion for every run, the retrieved chunks with their scores and sources, tool arguments and results, and a stable run ID. This is the raw material for audits, for compliance, for reproducing a specific failure after the fact.

Evals and metrics answer "is this getting better or worse?" Metrics are counters and gauges: tokens per request, latency percentiles, cost per resolved task, tool-call rate, cache hit rate. Evals are the scored test cases you run against a regression set when you change the prompt or the model. Tracing tells you what broke; evals tell you whether your fix stuck.

The eval loop is where most teams quietly drop the ball, so let me be concrete about what it looks like. I keep a regression set of 50–100 real, de-identified interactions — a few per failure mode the team has hit. When I change a prompt, a retrieval strategy, or a model version, I run the set and score it with a mix of exact checks (the answer contains the correct tracking number) and rubric-based checks (did the agent escalate when the tool returned an error). The output is a pass rate and a diff against the previous run. If the change improves the reported incidents but drops the eval score by three points, I do not ship it. That eval set is the only reason I can move fast on prompts without being scared — the trace tells me what changed, and the eval tells me whether it is okay.

The Anatomy of a Trace

Let me show you what a real agent trace looks like. Take a question like "What is the status of order SH-991?" The root span splits into children, and each child carries its own numbers:

request (root span)                          duration 3.1s   cost $0.084
├── auth + routing                           0.4ms           -
├── retrieval (vector store)                 28ms            top_k=5
│     └── 1 chunk returned (score 0.71)                      731 tokens
├── prompt assembly                          2ms             prompt=2,104 tokens
├── llm call 1                               1.9s            input 2,835 / output 142
│     └── decision: call_tool(lookup_tracking)
├── tool: lookup_tracking("SH-991")          120ms           400 error: not found
├── llm call 2                               860ms           input 3,112 / output 89
└── final answer                                              3,412 tokens total

That one trace told me exactly what went wrong in the Jeddah case: retrieval returned a single low-confidence chunk, the tracking tool returned a hard error, and the model answered anyway instead of asking for a corrected reference number. Three spans, three failure points, one trace. Without it I would have spent days guessing.

The ecosystem has settled on this shape. OpenTelemetry defined semantic conventions for generative AI (the gen_ai.* attribute family — gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens) so traces from different providers and frameworks can be correlated in one tool. On top of the OTLP transport, you get purpose-built backends — I have used LangSmith and Langfuse, and both will happily ingest OTLP traces now. You do not need to pick between a tracing backend and an APM; they speak the same wire format.

What I Actually Capture Per Run

Here is the concrete capture contract I use. If a run produces these fields, I can debug any incident in under an hour:

run_id — stable across retries, correlatable to the customer session
model — provider, model name, and version
temperature / top_p / max_tokens — the sampling config at the time
system prompt — the full text, version-hashed
retrieved chunks — text, source, and score for each
tool calls — function name, serialized arguments, result, error if any
token counts — prompt, completion, and total per call
latency — per span and total
cost — cents per call, from the token counts × current price
feedback — thumbs up/down or a follow-up human rating when available

I write this to a Postgres table with a JSONB column for the trace plus a few indexed columns for querying, and I ship the same data to a tracing backend for the visual waterfall view. The table is the audit trail; the backend is the debugger.

A Minimal Instrumented Loop

Here is a minimal agent loop with tracing bolted on — no framework, just the OpenTelemetry SDK and a couple of spans. This is the smallest thing I would actually deploy:

import json
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer("agent.observability")

def run_agent(goal: str, retriever, llm, tools, max_steps: int = 5):
    with tracer.start_as_current_span("agent.run") as root:
        root.set_attribute("goal", goal)
        context = []
        for step in range(max_steps):
            with tracer.start_as_current_span(f"step.{step}") as step_span:
                with tracer.start_as_current_span("retrieve") as ret_span:
                    chunks = retriever(goal)
                    ret_span.set_attribute("chunks.count", len(chunks))
                    ret_span.set_attribute(
                        "chunks.scores", json.dumps([c.score for c in chunks]))
                with tracer.start_as_current_span("llm.call") as llm_span:
                    llm_span.set_attribute("gen_ai.request.model", "your-model")
                    decision = llm.decide(context, chunks, tools)
                    llm_span.set_attribute(
                        "gen_ai.usage.input_tokens", decision.input_tokens)
                    llm_span.set_attribute(
                        "gen_ai.usage.output_tokens", decision.output_tokens)
                if decision.is_final:
                    return decision.answer
                with tracer.start_as_current_span("tool.call") as tool_span:
                    tool_span.set_attribute("tool.name", decision.tool_name)
                    tool_span.set_attribute(
                        "tool.arguments", json.dumps(decision.arguments))
                    result = tools<a href="**decision.arguments">decision.tool_name</a>
                    tool_span.set_attribute("tool.result", json.dumps(result))
                context.append((decision, result))
        raise RuntimeError("step budget exhausted")

The key habit: every span carries the input and output that moved through it. A span that only records duration is a pretty waterfall with no forensic value. When the trace shows chunks.scores = [0.71] and the tool result is a hard error, the debugging is over before it starts.

What I Actually Learned Debugging Real Runs

Once tracing was live, the failure modes stopped being mysterious and became a checklist. These are the ones I hit, in order of frequency:

Retrieval returned nothing, and the model guessed. The most common silent killer. The fix is never in the prompt; it is in the retrieval quality — better chunking, higher top-k, a fallback query. The trace proves it in one line.
Context bloat. A run that should use 4,000 tokens was sending 28,000 because history was never summarized. Latency doubled, cost quadrupled, and quality went down. Token counts per span expose this instantly.
Tool arguments out of schema. The model invented a field or formatted a date wrong. With arguments logged, you can add a validation layer or tighten the tool description in one iteration.
Model drift after a provider update. A silent provider-side change degraded one customer segment. Because I had model version on every span, I could see the version flip exactly when accuracy dropped.
Cost spikes tied to loops. One agent was retrying the same failing tool call five times per conversation, doubling the bill. Step budgets are not a guardrail question; they are an observability question — the trace showed the loop.

I keep a running rule now: if a production incident takes more than an hour to explain, the tracing is insufficient. Not the model, not the prompt — the tracing.

When You Do NOT Need Full Observability

Honest section, because not everything needs a tracing stack. If your use case is a stateless, single-shot LLM call — a summarizer, a classifier, a translation step with no tools and no retrieval — then a plain log of prompt, completion, model, and token count is 90% of the value at 10% of the setup cost. Ship that first.

Similarly, if you are prototyping and have fewer than a few hundred calls a day, the tracing backend is overkill. Log to a JSON file. Add the full stack when you hit real users, real money, or a multi-step agent loop. The rule of thumb: one LLM call, no tools, no state → simple logging. A loop, tools, retrieval, or autonomy → tracing, non-negotiable.

There is also a spectrum between the two extremes, and most teams are on it. If you are at the "loop with tools" stage but not yet at "needs alerting," start with the logging contract and the eval set, and defer the backend until the trace viewer is actually going to save you time. The mistake I see is the reverse: teams buy the expensive backend first and never build the logging contract, so they have a beautiful waterfall view of runs that do not contain the one field that would explain the incident. The data comes first. The tool is the last mile.

Alerting: Making the Trace Do Work

The final layer is alerting, and it is the one that turns observability from a postmortem tool into a prevention tool. I set alerts on the metrics that predict incidents before customers feel them:

Cost per resolved task over a rolling day — when it spikes 30% above baseline, a loop or a context bloat is likely eating money.
Tool-call rate per run — when an agent that should call a tool in 80% of runs suddenly calls it in 30%, it has started guessing from training data. That is the "silent degradation" failure mode, caught in hours instead of weeks.
Error rate on tool executions — a spike means a downstream API broke, and the agent is about to hallucinate around it.
Average retrieval score — a creeping drop means the chunking or the embeddings drifted, and every answer will get worse.

Alert thresholds have to be tuned to each system, but the principle is universal: alert on drift from the system's own baseline, not on absolute numbers. A 500-millisecond latency spike means nothing for a batch summarizer and everything for a chat product. Your historical traces are the baseline; the alert just detects the divergence.

The Practitioner's Checklist

Before you call an LLM system production-ready, go through this list:

[ ] Every run has a stable run_id correlated to the user session
[ ] Prompt and completion are logged verbatim, with model name and version
[ ] Retrieved chunks carry source and score
[ ] Tool calls log arguments, result, and error
[ ] Token counts (input/output) and cost are recorded per call
[ ] Latency is measured per span, not just end-to-end
[ ] A trace viewer can reconstruct any run in under five minutes
[ ] A regression eval set exists, and it runs on every prompt change
[ ] Alerts fire on cost-per-task, tool-call rate, and error-rate thresholds
[ ] You can answer "what changed" for any incident — model, prompt, or data

The Aftermath

After the Jeddah incident we rebuilt the agent's tracing from scratch, added a guard that asks the customer to re-confirm the reference number when retrieval returns nothing, and put the whole thing behind the observability stack I described. Two months later, the client asked what the new dashboards cost. When I told him, he laughed and said the alternative — three more weeks of confident wrong answers — would have cost his dispatch team more than that in a single day.

Your LLM will fail silently. It is not a question of whether; it is a question of how long you do not know about it. Tracing, logging, and evals are the difference between finding out in hours and finding out from an angry customer.

If you are starting today, do not buy a tool. Add the run ID, log the prompt and completion, and put token counts on every call. That is the whole foundation. Everything else — the backends, the dashboards, the alerting — is polish on top of a habit you have to build first.

*Gulshan Yad

Flutter State Management: Riverpod vs Bloc in 2026

Gulshan Yadav — Sat, 29 Aug 2026 13:30:00 +0000

Two state management libraries, real production apps behind both. A criteria table, honest scores, and a decision rule you can apply to your own project.

Every Flutter developer reaches the same junction within their first month: Riverpod or Bloc. I have been asked this question in some form for years, and I have shipped both — Riverpod in a consumer finance app, Bloc in a large enterprise product with multiple teams touching the same codebase. Both work. Both have passionate defenders. And the answer, as with most engineering questions, depends entirely on your context.

This article is that question answered honestly: a criteria table, each tool scored on the dimensions that actually matter when real teams build real apps, and a decision rule at the end. I am not going to tell you one is universally better, because that would be a lie you would discover in week three.

The Criteria That Actually Matter

Marketing material for both libraries sounds identical. These are the criteria I have learned to weight, from shipping both in production:

Learning curve. How long before a competent developer writes idiomatic code, not copy-pasted code?
Boilerplate and ceremony. How many lines does a simple feature actually take?
Async handling. How well does it model loading, success, and error states — which is most of a real app?
Testability. How easy is it to test business logic in isolation from widgets?
Dev tools and debugging. When state is wrong, how fast can you find it?
Scalability and team ergonomics. How does it behave when 8 developers work in the same repo?
Ecosystem and maintenance. Is it alive, documented, and surrounded by answers?

The Criteria Table

Criterion	Riverpod	Bloc
Learning curve	8/10 — gradual, small concepts build up	6/10 — events/emitters/states take a mental shift
Boilerplate	7/10 — lean for simple cases, still explicit	5/10 — more files and classes per feature
Async handling	9/10 — AsyncValue is a first-class citizen	8/10 — state + sealed classes, manual but clear
Testability	8/10 — providers are easy to override	9/10 — pure event-to-state, the classic winner
Dev tools	7/10 — growing, decent	9/10 — Bloc Inspector is excellent
Team ergonomics	7/10 — flexibility invites inconsistent patterns	9/10 — enforced structure scales to many devs
Ecosystem	8/10 — active, mainstream	9/10 — the most battle-tested large codebase story

No tool wins every row, and that is the point — the correct choice is a function of your team, your app, and your tolerance for structure.

Riverpod — Score: 7.5/10, the Flexible Modern Default

Riverpod is the direct descendant of Provider, written to fix Provider's flaws: no compile-time safety, no easy testing, no way to combine providers. It rethinks state management around a single concept — the provider — and gives you compile-time safety, easy overrides for testing, and async state handled natively.

Learning curve: 8/10. The mental model is small: a provider is a piece of state that knows how to recreate itself. A simple counter takes one provider and a few lines:

final counterProvider = StateProvider<int>((ref) => 0);

class CounterView extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Scaffold(
      body: Center(
        child: FilledButton(
          onPressed: () => ref.read(counterProvider.notifier).state++,
          child: Text('Count: $count'),
        ),
      ),
    );
  }
}

That is the whole pattern. ref.watch rebuilds the widget when state changes, ref.read reads without subscribing. New developers pick this up in an afternoon.

Async handling: 9/10. This is Riverpod's best feature. AsyncValue models loading, data, and error as a single sealed type, so async state stops being an ad-hoc boolean-and-null dance:

final userProvider = FutureProvider<User>((ref) => fetchUser());

// in a widget:
final userAsync = ref.watch(userProvider);
return userAsync.when(
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => Text('Error: $e'),
  data: (user) => Text(user.name),
);

No separate loading flags, no null checks, no forgotten error states. Every consumer of the provider gets correct async handling by default.

Testability: 8/10. Providers are overridable, which makes testing straightforward:

@override
Widget build(BuildContext context, WidgetRef ref) {
  return ProviderScope(
    overrides: [userProvider.overrideWithValue(AsyncValue.data(fakeUser))],
    child: const MyApp(),
  );
}

You swap a real provider for a fake in one line. It is clean and it works.

The honest weak spots. Riverpod gives you freedom, and freedom means inconsistency. In a codebase with several developers, I have seen the same feature implemented three different ways because Riverpod offers several valid approaches — StateProvider, Notifier, AsyncNotifier, StreamProvider — and nothing forces a team to agree on one. The Bloc Inspector also has no true rival: Riverpod's tooling is decent but does not give you the same time-travel-style event timeline. And the ConsumerWidget / ConsumerStatefulWidget split confuses newcomers until they internalize it.

The honest verdict: Riverpod is the correct default for most apps and most teams — small mental model, superb async handling, easy testing, and fast to write. Choose it when you value developer velocity, when the team is small, or when you are building greenfield and want to move quickly.

Bloc — Score: 8/10, the Structured Heavyweight

Bloc takes the opposite philosophy. State is an immutable value, and the only way to change it is to send an event through a bloc that maps events to states. Everything is explicit, everything is typed, and everything is testable by construction.

Learning curve: 6/10. The concepts are simple — event in, state out — but the ceremony is real. The same counter requires more files and a mental shift from "widget owns state" to "bloc owns state":

abstract class CounterEvent {}
class CounterIncremented extends CounterEvent {}

class CounterBloc extends Bloc<CounterEvent, int> {
  CounterBloc() : super(0) {
    on<CounterIncremented>((event, emit) => emit(state + 1));
  }
}

And to use it in a widget you add a BlocProvider and watch with context.watch<CounterBloc>(). Every feature means an event class, a bloc class, and a state definition — usually spread across files. The first week is slower, and teams new to Bloc feel it.

Async handling: 8/10. Bloc handles async explicitly. You emit a loading state, do the work, and emit a success or failure state — usually with sealed classes so every state is exhaustive:

sealed class UserState {}
class UserLoading extends UserState {}
class UserLoaded extends UserState {
  final User user;
  UserLoaded(this.user);
}
class UserError extends UserState {
  final String message;
  UserError(this.message);
}

It is more code than AsyncValue, and you write the state machine yourself — but you control it completely, and nothing is hidden from you.

Testability: 9/10. This is Bloc's crown. A bloc is pure logic: events in, states out, no widgets involved. Testing is as clean as it gets:

test('increments the counter', () {
  final bloc = CounterBloc();
  bloc.add(CounterIncremented());
  expect(bloc.state, 1);
});

No widget tree, no mocking framework, no async pump. Pure function-of-input-to-output testing, which is why enterprise teams love it.

Dev tools: 9/10. The Bloc Inspector is genuinely excellent — you can watch every event and every state transition in a timeline, which turns debugging a bad state into a searchable history instead of a guessing game. It is the single best debugging experience in Flutter state management.

The honest weak spots. The boilerplate is real and grows with complexity. For a simple feature, Bloc is objectively more work than Riverpod. The strictness that helps a large team also slows a solo developer down, and junior developers produce Bloc code that is correct but bloated — one bloc class per screen, events that do one thing and emit three states. And because the structure is so explicit, refactoring a Bloc architecture touches more files than the equivalent Riverpod change.

The honest verdict: Bloc is the right choice when your app is large, your team is multiple developers, or your state logic is complex enough that enforced structure saves more time than it costs. It is the library that scales — not to more code, but to more people and more years of maintenance.

The Real-World Decision Rules

Here is the decision rule I now apply with clients, in order:

1. Small app, small team, greenfield, want to ship fast? Use Riverpod. The learning curve is lower, the code is shorter, and AsyncValue removes a whole class of async bugs for free. You can rebuild with structure later if you need to — and if you started on Riverpod, your feature code is mostly presentation logic, so the migration cost is contained.

2. Multiple developers, long-lived codebase, complex state flows? Use Bloc. The enforced event-to-state structure is not overhead; it is the communication protocol your team uses to avoid stepping on each other. The Inspector and the pure testability more than pay for the ceremony. On a codebase with 6+ people, I choose Bloc every time.

3. Already have a codebase in one of them? Do not switch for fashion. A migration of a working app costs weeks and produces zero user-facing value. I have told teams this directly: your problem is not the library. Unless a concrete pain — async bugs, unmanageable boilerplate, impossible testing — is attributable to the choice, keep what works and improve the code.

4. Mixed seniority on the team? Match the structure to the weakest link. If your team is mostly seniors, Riverpod's freedom is a feature. If you onboard juniors constantly, Bloc's rigidity trains them to write consistent code. The library is, in part, a training mechanism.

A Worked Example: Scoring Your Own Situation

Let me apply the rule to the two projects I mentioned.

The consumer finance app (Riverpod). Small team, three developers, heavy async — live balances, transaction history, push notifications. The AsyncValue model alone removed dozens of "forgot to handle the error state" bugs. We shipped features in days, not weeks. Bloc would have been slower with zero benefit at this team size.

The enterprise product (Bloc). Eight developers across three teams touching the same modules, a codebase that will be maintained for years, and strict QA requirements. The event-to-state pattern gave every team a uniform way to read any screen's logic, and the Inspector made support escalations ten times faster. Riverpod's flexibility would have produced five inconsistent patterns in a codebase that large.

Same framework, two opposite answers, both correct — because the decision was driven by team size and codebase lifetime, not by which library was "better."

The Numbers That Decide It

The real trade-off, compressed into the numbers that matter: development speed (Riverpod wins for small teams), debugging speed (Bloc wins via the Inspector), test maintenance (Bloc's pure logic tests are cheaper to keep green), and codebase consistency (Bloc forces it, Riverpod requires discipline). A solo developer or a three-person startup is optimizing the first number. A 50-developer org is optimizing the last three.

The decision rule, one sentence: Riverpod for velocity and async ergonomics on small teams; Bloc for structure, testability, and multi-developer scale. Score your own situation honestly — team size, app complexity, how long the codebase will live — and the choice stops being a flame war and becomes a calculation.

I have shipped both in production apps with real users and real bugs. Riverpod made me faster; Bloc made my codebase easier to reason about at scale. The best tool is the one that matches the size and shape of the problem you actually have — so measure your team, not your preference.

*Gulshan Yad

RAG Evaluation: How to Know Your Retrieval Isn't Broken

Gulshan Yadav — Sat, 29 Aug 2026 02:30:00 +0000

The metric taxonomy for RAG — retrieval metrics, generation metrics, the eval sets you build, and the numbers that tell you which layer is failing.

I was reviewing a team's RAG demo at a meetup last year. The presenter asked a question, the system retrieved a chunk, and the LLM produced a fluent, well-cited answer. It looked perfect. I asked the question nobody in the room could answer: "What is your hit rate?" The presenter blinked. "What do you mean, hit rate?" We checked their logs. The retrieval was returning the correct chunk about 30% of the time — and because the demo questions were chosen for answers the system could find, nobody had noticed.

That is the whole story of RAG evaluation in one incident: fluent output hides broken retrieval. The LLM is a confident text generator, so a wrong chunk in the context produces an answer that sounds exactly as good as a right one. The only way to know which is which is to measure the layers independently, with metrics, on data you control.

I have written at length about why retrieval quality matters more than model choice. This article is the how: the metric taxonomy, the eval sets you build, the tooling that runs the numbers, and the honest rules for when this evaluation is worth the effort.

Why You Cannot Just "Look at Answers"

The trap is that humans are terrible at evaluating RAG output by eyeballing ten examples. Three reasons:

Fluency is not correctness. The model writes with equal confidence whether the retrieved chunk is right or wrong. A human reader cannot distinguish "grounded in the right source" from "plausible-sounding" without checking the source themselves — and nobody does that for every answer.
You cannot see the failure that did not happen. A demo question that happens to retrieve well tells you nothing about the 90% of real questions that do not. The only way to see the failure distribution is to run a fixed, labelled set repeatedly.
The failure lives in the retrieval layer, not the output. If retrieval returns the wrong chunk, no amount of prompt or model tuning fixes the answer. To know where to invest, you must be able to score retrieval and generation separately. A single "did the answer look good" number tells you nothing about where to fix things.

So the entire practice of RAG evaluation reduces to one question, asked with data: which layer is losing quality, retrieval or generation?

The Metric Taxonomy

RAG evaluation splits into two families, and the biggest mistake I see is teams measuring one family and calling it done.

Retrieval Metrics — "Did we find the right source?"

These score the retriever alone, before the LLM ever sees the context:

Hit rate / Recall@k. Out of all queries, what fraction had the correct document in the top-k retrieved results? This is the single most important number in all of RAG. If your hit rate at k=5 is below 80%, your retriever is the problem, full stop.
MRR (Mean Reciprocal Rank). Where in the ranked list did the correct document appear? A system that always returns the right chunk at position 1 has MRR 1.0; one that buries it at position 4 is worse even if it still "hits." Latency and context budget reward high ranks.
Precision@k. Of the k retrieved chunks, what fraction were relevant? This matters because irrelevant chunks cost tokens and confuse the model. A system that hits at position 5 but returns four noise chunks above it will generate worse answers than one that hits cleanly at position 1.
NDCG. The graded version — accounts for whether near-miss chunks are partially relevant. Overkill for most teams; MRR and hit rate cover 95% of decisions.

Generation Metrics — "Did the answer use the source correctly?"

These score the LLM's output against the retrieved context:

Faithfulness. What fraction of the claims in the answer are supported by the retrieved context? This is the "is it grounded or hallucinating" number. It is the metric that would have caught my client's wrong-dosage disaster if they had run it.
Answer relevancy. Does the answer actually address the user's question? An answer can be perfectly faithful to the retrieved context and still not answer what was asked.
Context precision. Of the retrieved chunks, how many were actually needed to produce the answer? High context precision means the retriever is giving the model clean, useful material.
Context recall. Could the answer have been produced from the retrieved chunks at all? This is generation-side view of the same hit-rate question.

The diagnostic logic: if hit rate or context recall is low, fix retrieval. If faithfulness is low, your retrieval is often still fine — the problem is prompt handling, context stuffing, or the model. These two families tell you exactly where to spend your engineering.

Building the Eval Set (The Part Everyone Skips)

Metrics are meaningless without a labelled set. This is the highest-leverage work in the entire pipeline, and it is the part most teams skip because it is not glamorous. The rule I use: start with 100–200 question–document pairs built from your real logs, not from happy-path examples a developer wrote.

How to build it:

Mine real queries. Pull the last month of actual user questions from your logs. These are your ground truth for what the system faces, not what you imagine it faces.
Label the ground truth. For each query, identify the document chunks that contain the correct answer. You are labelling the answer source, not the answer itself. This is tedious work, and it is exactly the work that makes every other number meaningful.
Include the hard cases. Multi-hop questions, questions with exact codes or SKUs, questions that require combining two documents. If your eval set has no hard cases, your metrics will look great and your production will not.
Version the set. It lives in your repo, in git. When you change the chunker, the embedding model, or the retriever, the same set tells you whether you got better or worse.

The honest advice: label 50 examples well before you label 200 badly. A clean small set beats a noisy large one, and you can grow it every week by having the team review a handful of real queries each.

Running the Numbers with RAGAS

You do not need to hand-score each answer. LLM-as-a-judge has matured enough that for faithfulness-type metrics it is reliable — the judge model scores whether claims are supported by context, which is a verification task, not a reasoning task. The library I reach for is RAGAS, which implements the retrieval and generation metrics above and scores a full eval set in one pass.

Here is the setup. Install, define your eval set as question/answer/context triplets, and run:

from ragas import evaluate
from ragas.metrics import (
    faithfulness,
    answer_relevancy,
    context_precision,
    context_recall,
)
from datasets import Dataset

eval_set = Dataset.from_list([
    {
        "user_input": "What is the refund window for annual plans?",
        "response": "Annual plans can be refunded within 14 days of purchase.",
        "retrieved_contexts": [
            "Annual subscriptions are eligible for a full refund within 14 days.",
        ],
        "reference": "Refund window for annual plans is 14 days.",
    },
    # ... 100+ more rows from your real logs
])

result = evaluate(
    eval_set,
    metrics=[
        faithfulness,
        answer_relevancy,
        context_precision,
        context_recall,
    ],
    llm=judge_model,  # a strong LLM acting as the judge
    embeddings=judge_embeddings,
)

result_df = result.to_pandas()
print(result_df[["context_precision", "context_recall",
                 "faithfulness", "answer_relevancy"]].mean())

A few honest notes on the tooling:

The judge model matters. Use a strong model — it is a verification pass, and a weak judge produces noise that hides real regressions. If you are on a budget, judge with a strong hosted model and only self-host the judge once your evaluation volume justifies it.
The reference field is your gold standard. For retrieval metrics, RAGAS scores context recall by checking whether the reference is contained in the retrieved chunks. The quality of your labels directly sets the quality of every number.
Run it in CI, not just on demand. A weekly run that compares today's metrics to last week's catches regressions from chunking changes, embedding swaps, or retriever config edits. The eval set has no value sitting in a notebook that nobody re-runs.

What the Numbers Actually Tell You

Reading the output is a diagnosis, not a score. Here is the decision table I work from:

Finding	What it means	What to fix
Hit rate low (<80% at k=5)	Retriever not finding the source	Chunking, embedding model, top-k, hybrid search
MRR low but hit rate okay	Right doc is buried	Re-ranking, larger top-k, better index params
Context precision low	Retrieval returns noise around the right doc	Tighter chunking, re-ranking, hybrid + fusion
Faithfulness low	Answer not supported by context	Context stuffing discipline, prompt hardening, model choice
Answer relevancy low	Not answering the question asked	Query understanding, reformulation, better instructions

The most common real-world pattern I see: teams with high faithfulness on the demo and low hit rate on the full set. That combination is a classic — retrieval returns irrelevant chunks for most real queries, and the LLM faithfully summarizes garbage. Fix retrieval first; the generation metrics will follow.

Online vs Offline Evaluation

Offline evaluation on a labelled set catches regressions you control. But it cannot catch the two failures that only appear with real traffic:

Query drift. Users ask things you never predicted. The eval set grows stale, and the system quietly rots against the questions it actually faces. The fix is a feedback loop: instrument production, log every query and its retrieved chunks, and add samples to the eval set weekly.
Silent degradation. A retriever config change or an embedding model update ships, retrieval quality drops, and nobody notices because no alert exists. The fix is scheduled re-evaluation in CI plus a guardrail: a model or config change does not merge unless the eval-set metrics hold or improve.

For online observability, track two lightweight numbers in production: retrieval coverage — the fraction of queries that return results above your relevance floor — and feedback signals — thumbs up/down, copy clicks, whether the user rephrased the question. Correlated with your weekly offline run, these catch the drift the labelled set cannot see.

When NOT to Over-Engineer Evaluation

The honest boundary, because evaluation has a cost:

If your RAG is a weekend project with a few dozen documents, hand-check answers and skip the harness. The effort is not worth it at that scale.
If you have no labelled set and no willingness to build one, do not buy metric tooling — you would be measuring noise. Start with 50 labelled pairs and grow from there.
If your failure cost is low — a demo, an internal tool nobody depends on — a light evaluation loop is enough. Reserve the full CI harness for systems where a wrong answer has a real cost, like a clinician-facing assistant or a legal research tool.

The rule: evaluation effort should track the cost of being wrong. A wrong answer in a customer-facing finance assistant is worth a full harness; a wrong answer in your personal note-summarizer is worth a glance.

The Practitioner's Checklist

[ ] You can answer "what is your hit rate at k=5" with a number, today
[ ] Retrieval and generation are scored separately; a single blended number is not trusted
[ ] Eval set has 100+ question–document pairs built from real logs, versioned in git
[ ] The set includes hard cases: multi-hop, exact codes, multi-document questions
[ ] Labels are reviewed by a human; the judge model only scores, it does not define truth
[ ] Retrieval metrics: hit rate, MRR, precision@k — tracked over time
[ ] Generation metrics: faithfulness, answer relevancy — tracked over time
[ ] A diagnostic table maps low metrics to the layer to fix (retriever vs prompt vs model)
[ ] Evaluation runs in CI on every model/config change; regressions block the merge
[ ] Production logs feed the eval set weekly so it does not go stale
[ ] You know when to stop — evaluation effort scales with the cost of being wrong

The Number That Changed the Room

That meetup demo ended with a different conversation than the presenter planned. We added hit rate to their monitoring, found the 30% number, and traced it to a chunking strategy that had never been tested against their real documents. Three weeks later retrieval was above 85%, and the fluent answers were finally grounded — not because the model changed, but because someone finally measured the layer underneath it.

When someone tells you their RAG is working, ask for their hit rate. If they cannot answer, the system is not evaluated, it is demoed. Build the set, run the numbers, and let the metrics point at the layer that is actually leaking quality. That is the entire discipline, and it is the difference between a system that sounds grounded and one that is.

*Gulshan Yad

OpenTelemetry vs Prometheus: Why You Almost Certainly Need Both

Gulshan Yadav — Fri, 28 Aug 2026 17:23:43 +0000

This gets framed as a choice, and it mostly isn't one. They occupy different layers, and a normal production setup runs both. Understanding why saves a lot of wasted migration effort.

What each one actually is

Prometheus is a metrics database with a query language. It scrapes numeric time series from your services, stores them, and lets you query them with PromQL. It is a backend: a place metrics live and are asked questions.

OpenTelemetry is a specification and a set of SDKs for producing telemetry. It defines how you instrument code to emit traces, metrics and logs, and it ships a Collector that receives, processes and forwards them. It is a pipeline: how telemetry gets from your code to wherever it is stored.

OTel does not store anything long-term. Prometheus does not instrument your code. Asking which to use is a little like asking whether to use a courier or a warehouse.

Where the overlap actually is

There is one real point of contention: metrics instrumentation.

Historically you added a Prometheus client library to your service, defined counters and histograms, and exposed /metrics for Prometheus to scrape. That works and is still widely deployed.

OpenTelemetry offers its own metrics SDK doing the same job, but vendor-neutrally — the same instrumentation can be exported to Prometheus, or to a commercial backend, or to several at once, without touching application code.

So the genuine question is not "Prometheus or OTel" but "Prometheus client libraries or OTel SDKs, in front of Prometheus?"

The answer for most teams

Instrument with OpenTelemetry. Store metrics in Prometheus.

The reason is not that OTel's metrics API is nicer — arguably the Prometheus client is simpler for pure metrics. It is that instrumentation is the expensive, sticky part. It is spread across every service, written by everyone, and rewriting it later is a large coordinated change nobody wants to schedule.

Backends are comparatively easy to change. If your instrumentation is vendor-neutral, swapping or adding a backend is a Collector config change. If your instrumentation is Prometheus-specific, it is a code change in every service.

Instrument once against a standard; keep the storage decision reversible.

The other reason: traces

Prometheus stores metrics. Metrics tell you that p99 latency rose. They cannot tell you which call in the request path caused it, because a metric is an aggregate — the individual requests were summed away.

Traces keep the individual request: every span, in order, with timing. When latency rises, a trace shows you it was a specific downstream call, on a specific code path, for a specific class of request.

Prometheus has no trace story. OpenTelemetry treats traces as first-class and links them to metrics through exemplars — so a spike in a histogram can carry a pointer to an actual slow request. In practice that link is the single most useful thing in the stack, and you only get it if traces and metrics come from the same instrumentation.

If you have only ever had metrics, this is the upgrade worth making. Most debugging time is spent going from "something is slow" to "this is what is slow", and that is precisely the gap traces close.

What a real setup looks like

Application code instrumented with OTel SDKs, emitting traces and metrics. An OTel Collector deployed per host or as a service, receiving that telemetry. From the Collector: metrics to Prometheus, traces to Tempo or Jaeger, logs to Loki. Grafana on top, querying all three.

The Collector is more useful than it first appears. Because everything passes through it, you can drop high-cardinality attributes, sample traces, redact fields that should never reach a vendor, and add resource attributes centrally. Doing any of that without a collection layer means redeploying every service.

The trap worth naming

Cardinality. Prometheus stores a separate time series for every unique combination of label values. Add a label with unbounded values — user ID, request ID, full URL path — and you generate millions of series. Prometheus will slow down and then fall over, and the failure looks like a Prometheus problem rather than an instrumentation problem.

OpenTelemetry makes this easier to do accidentally, because trace attributes are naturally high-cardinality and it is tempting to promote them to metric labels. Traces handle high cardinality fine. Metrics do not. Keep the distinction: identifying details belong on spans, and metric labels stay bounded and low.

When you do not need OTel

If you run a handful of services, you already have Prometheus client libraries working, and nobody is asking questions your metrics cannot answer — there is no urgent reason to migrate. It is real work for benefit you may not currently need.

The trigger to adopt it is usually one of: you want distributed tracing; you are tired of debugging across service boundaries with only aggregates; or you want to stop being locked to one backend's instrumentation format.

Summary

Not competitors, and not really a choice. OpenTelemetry is how telemetry is produced and moved; Prometheus is where metrics land and get queried. Instrument with OTel because instrumentation is the part you cannot cheaply redo, keep Prometheus as the metrics backend because it is excellent at that job, and add tracing because it answers the questions metrics structurally cannot.

Originally published at https://www.misar.blog/@mrgulshanyadav/articles/opentelemetry-vs-prometheus-why-you-almost-certainly-need-both

Downloading Files to the Device in Flutter

Gulshan Yadav — Fri, 28 Aug 2026 13:30:00 +0000

So, in this article, I will be showing you how you can download files to the device in Flutter — and actually save them somewhere the user can find them.

This sounds trivial until you ship it. I have debugged more "the download finished but the file is nowhere" reports than I can count, and the root cause is almost always the same: the code downloads bytes correctly and then writes them to a location the user has no way to reach, or Android's storage rules block the write silently. Every generation of Android changes the rules slightly, which is why a tutorial from two years ago will compile fine and then fail on a modern device.

The good news: the pattern is stable, the packages are mature, and once you understand where each platform expects files to go, the whole thing is about thirty lines of Dart.

For this purpose, we need to add these dependencies in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  dio: ^5.4.0
  path_provider: ^2.1.0
  permission_handler: ^11.3.0

dio handles the actual download with progress reporting and robust error handling.
path_provider gives you the platform's correct directories — the ones that exist on the device, not paths you guess.
permission_handler lets you ask for storage permission cleanly on Android.

Let's jump into the coding part.

Step 1: Where Files Are Allowed to Go

Android and iOS have completely different rules about where a downloaded file may live, and this is the heart of the whole article.

On iOS, there is one real answer: the Documents directory (visible in the Files app) or, for media, the app's own sandbox. Users can't browse the whole filesystem anyway, so you save to a directory your app owns and expose.

On Android, since Android 10 (API 29), scoped storage means your app cannot just write anywhere. The honest options are:

App-specific external directory — getExternalStorageDirectory(). No permission needed, but the folder is hidden from the user's file manager on many devices unless your app exposes it.
The public Downloads folder — via the MediaStore or getDownloadsDirectory(). This is what users expect when they tap "download": the file lands in Download/ and shows up in their file manager. This is the target I use for anything the user is meant to keep.

The rule I follow: save to the app's own directory for internal artifacts, save to the public Downloads folder when the user explicitly asked to download something they will open later.

Step 2: Android Permissions

For the public Downloads folder on modern Android, the permission story is more forgiving than people expect — Android 10+ allows writing to Downloads via MediaStore without the old WRITE_EXTERNAL_STORAGE monster permission for most cases. But you will still hit permission requests depending on the device and Android version, so handle it cleanly:

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission
    android:name="android.permission.WRITE_EXTERNAL_STORAGE"
    android:maxSdkVersion="28" />

The maxSdkVersion="28" matters. On Android 9 and below the old storage permission applies. On Android 10 and above scoped storage replaces it, and declaring the permission unconditionally triggers confusing runtime prompts on devices that no longer need it. This single attribute has saved me a surprising amount of support-ticket pain.

Step 3: The Download Function

Here is a complete, production-shaped download using dio, with a progress callback and explicit save locations:

import 'package:dio/dio.dart';
import 'package:path_provider/path_provider.dart';

Future<String?> downloadFile({
  required String url,
  required String fileName,
  void Function(double progress)? onProgress,
}) async {
  final Dio dio = Dio();

  Directory? dir;
  try {
    dir = await getDownloadsDirectory();
  } catch (_) {
    dir = null;
  }
  // Fallback for platforms without a Downloads directory.
  final String savePath =
      '${(dir ?? await getApplicationDocumentsDirectory()).path}/$fileName';

  final Response response = await dio.download(
    url,
    savePath,
    onReceiveProgress: (int received, int total) {
      if (total != -1 && onProgress != null) {
        onProgress(received / total);
      }
    },
  );

  if (response.statusCode == 200) {
    return savePath;
  }
  return null;
}

A few details worth your attention:

getDownloadsDirectory() comes from path_provider and returns the platform's real downloads location. On Android it maps to the public Downloads folder; on iOS it returns the app's Documents directory so the file appears in the Files app.
The fallback to the documents directory covers desktops and any platform quirk where a Downloads directory does not exist.
The onReceiveProgress callback is what lets you render a progress bar. Pass it straight into a ValueNotifier or a state object and the UI updates live.
dio.download streams the file to disk instead of holding the whole thing in memory, so a 500 MB file will not OOM your app.

Step 4: Calling It From the UI

The wiring is straightforward. Here is a minimal screen that downloads a file and reports progress:

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

  @override
  State<DownloadButton> createState() => _DownloadButtonState();
}

class _DownloadButtonState extends State<DownloadButton> {
  double _progress = 0;
  bool _downloading = false;

  Future<void> _startDownload() async {
    setState(() {
      _downloading = true;
      _progress = 0;
    });

    final String? path = await downloadFile(
      url: 'https://example.com/files/invoice.pdf',
      fileName: 'invoice.pdf',
      onProgress: (p) => setState(() => _progress = p),
    );

    if (!mounted) return;
    setState(() => _downloading = false);

    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(path != null
            ? 'Downloaded to $path'
            : 'Download failed. Check your connection.'),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisSize: MainAxisSize.min,
      children: [
        if (_downloading)
          LinearProgressIndicator(value: _progress)
        else
          FilledButton(
            onPressed: _startDownload,
            child: const Text('Download invoice'),
          ),
      ],
    );
  }
}

That is a complete, working download flow: tap, progress, file on the device.

Step 5: File Names and Collisions

The last detail that separates a demo from a production app is file naming. Two users downloading the same invoice, or one user downloading the same report twice a day, produce collisions — and depending on the platform, the second file either silently overwrites the first or fails. The pattern I use:

import 'package:path/path.dart' as p;

Future<String> uniqueSavePath(Directory dir, String fileName) async {
  final File file = File('${dir.path}/$fileName');
  if (!await file.exists()) return file.path;

  final String ext = p.extension(fileName);
  final String base = p.basenameWithoutExtension(fileName);
  File candidate = file;
  int i = 1;
  while (await candidate.exists()) {
    candidate = File('${dir.path}/$base($i)$ext');
    i++;
  }
  return candidate.path;
}

This gives you report.pdf, report(1).pdf, report(2).pdf — the convention every file manager already uses, so users instantly understand it. Overwriting a user's previous download without asking is a data-loss bug; never let the second download silently clobber the first. If you prefer, you can also ask first with a dialog — but in my experience the (1) suffix pattern removes the question entirely and users prefer it.

Important Notes

Here is what will bite you in production, in rough order of frequency:

Scoped storage is not optional. On Android 10+, writing to arbitrary paths returns errors or silently no-ops. Always use getDownloadsDirectory() or the MediaStore instead of hardcoding /storage/emulated/0/Download. If you hardcode, you will get "download succeeded" in the log and "file not found" in the UI — I have seen exactly that combination in a production app.
getDownloadsDirectory() returns null on some platforms. Android can return null on certain devices and API levels. The fallback I showed is not a nice-to-have; it is the difference between a crash and a working download on those devices.
HTTPS is mandatory on modern platforms. Android 9+ and iOS both block cleartext HTTP by default. If your file URL is http://, the download will fail with a connection error. Serve files over HTTPS, or the fix is a per-domain network-security exception, which you should avoid shipping.
Large files need a resume story. A 500 MB download that dies at 90% because the user locked their phone is a bad day. dio supports DownloadRange for resumable downloads — persist the received byte count and resume from there. It is more code, and it is worth it for anything over a few tens of megabytes.
The user may want to share the file. After download, use share_plus to let them send it. Combine the two and you have the flow every invoice, report, and receipt app wants.
iOS background downloads are a separate topic. The dio approach keeps your app foreground. If a client asks for "download even when the app is closed," that is a background transfer session on the native side and a much bigger project. Say so up front.
Sanitize the file name from the server. If your download URL ends in a user-controlled name, strip slashes, spaces, and path separators before building the save path. A name like ../../etc/something on an unsanitized path is a vulnerability you do not want to debug after the fact.

A Workflow Note From the Field

I hit this problem most often in document-heavy apps — a logistics client wanted field agents to pull delivery manifests and store them offline, and an accounting client wanted report exports to land in Downloads for their auditors. When the requirements get that specific — exact file names, deterministic folders, resume behavior — I sketch the whole flow end to end before writing the app code, the same way I prototype an automation in a builder like misar.dev before committing to implementation. The pattern holds: decide where files live, decide what happens on failure, then write the thirty lines.

A Quick FAQ

Does this work for media files that should appear in the gallery? Partially. For photos and videos, the correct target on Android is the MediaStore (MediaStore.Images / MediaStore.Video) so they register in the gallery, not just the Downloads folder. That is a slightly different code path from the one above — same dio download, different destination.

Can I download multiple files at once? Yes, and you should not overthink it — run several dio.download calls in parallel and report aggregate progress. What you should not do is spin up a thread per file on the platform side; Dart's async model handles concurrency natively.

Do I need permission_handler at all? For downloads to the app's own directories and to the public Downloads folder on Android 10+, usually not. The permission code is a fallback for older Android versions and specific device quirks. Keep it for the maxSdkVersion=28 path, not for the modern one.

What about storing the download in a database? For offline-first apps, the pattern is to save the file to the app's documents directory and store its path in your database, rather than relying on the public Downloads folder. That way your app can open it without user permission, and the user-facing export is a separate optional step.

That's it — a complete file-download implementation in Flutter that lands files where users can actually find them, with progress reporting, collision-safe naming, and the permission handling that keeps it working on modern Android.

I have also written about file uploads to storage services and handling large media in Flutter — comment below with your download use case and I'll cover it next.

*Gulshan Yad

The Best Self-Hosted LLMs in 2026 — and How I Deployed Them

Gulshan Yadav — Fri, 28 Aug 2026 02:30:00 +0000

A practical field guide to running open-weight LLMs on your own hardware — which models, which serving stacks, and the cost math nobody puts on a blog post.

A fintech client called me in January with a problem that is getting more common by the month: their compliance team had banned every external AI API. No data leaves the building, they said. The analyst who wanted to chat with their internal documents would just have to wait. I told them they did not have to wait — they could run the model on hardware they already owned.

Three weeks later we had a 70B-class model serving the entire company on two GPU boxes, handling their document Q&A, their support triage, and a chunk of their internal code review. The cost per million tokens was a fraction of what the hosted API would have billed, the data never left the office, and the compliance team slept better. This article is that deployment, generalized: how I think about open-weight models, which ones I actually reach for, how I serve them, what the hardware math looks like, and the honest list of things that go wrong.

Why Self-Host at All

Let me state the case plainly, because there are good reasons and bad reasons to self-host, and you should know which one you have.

The good reasons:

Data sovereignty. The model weights are open and your inference runs on your hardware. No prompts, no logs, no context ever crosses your perimeter. For regulated industries — finance, health, legal, defense — this is not a preference, it is a requirement.
Cost at scale. If you run heavy inference volumes, the per-token cost of a hosted API compounds into numbers that buy you a GPU every few months. I have watched clients burn through a server's worth of API spend inside one quarter.
Latency and predictability. No network hop, no shared-tenant queue, no rate limits. A local model responds in the same milliseconds whether it is 9 a.m. or 3 a.m., and you control exactly what runs.
Control. You own the model version, the quantization, the prompts, and the upgrade schedule. Nothing on the provider side changes under you.

The bad reasons:

"It's cheaper." Up front it is not. GPUs are expensive, electricity is real, and your time is not free. Self-hosting only pays off at sustained volume, and I will give you the math to check your own number below.
"It's more private" without knowing what private means. If your concern is a specific compliance rule, verify self-hosting actually satisfies it before buying hardware. Some privacy requirements are about how the vendor handles data, and a well-contracted vendor may already meet them.
"We want the best model." If your task needs the absolute state of the art, self-hosted open weights are months behind the biggest closed frontier models, and for some workloads that gap is the difference between useful and not.

Decide which column you are in before you spend a rupee on silicon.

The Model Landscape in 2026

The open-weight ecosystem moves fast, but the tiers have been stable enough to reason about. Here is how I categorize what is available today, and the hardware each tier realistically needs.

Tier	Representative models	What it is good at	VRAM you need
Small (1–4B)	Phi-4, Llama 3.2 3B, Qwen 2.5 3B	Classification, extraction, routing, single-purpose tasks	4–8 GB
Mid (7–14B)	Llama 3.1/3.3 8B, Qwen 2.5 14B, Mistral 7B	General chat, summarization, light reasoning on one GPU	10–24 GB
Large (30–40B)	Qwen 2.5 32B, Llama 3.1 70B (quantized)	Strong reasoning, coding, agent loops on a single big GPU or two	24–48 GB
Frontier open (70B+)	Llama 3.3 70B, DeepSeek R1 distill variants, Qwen 3 flagship	Best open quality; needs multi-GPU or heavy quantization	48 GB+

The honest guidance: most production workloads do not need the frontier tier. A routing model that decides which sub-agent gets a task, an extraction model that reads invoices, a summarizer for internal reports — those are 3B to 8B jobs that run on a single GPU and answer in a few hundred milliseconds. Save the big models for the tasks where reasoning quality actually changes the business outcome.

The Serving Stack, Ranked by Where You Are

The model file is only half the story. The serving layer decides your throughput, your latency, and how much of your weekend you spend fighting it. My recommendations, in order:

Ollama — the start-here option. A single binary, a pull command, and an OpenAI-compatible endpoint out of the box. Perfect for one machine, one developer, or a small team that just needs a local model. It is not a serious production serving layer at scale — it will get you to the demo, then you migrate.

llama.cpp — the edge and CPU option. Runs quantized GGUF models on CPU, on Macs, on laptops, and even on Raspberry Pi-class hardware. When a client needs a model in the field with no GPU, llama.cpp is the tool. Expect modest tokens per second — fine for interactive use, wrong for high-throughput serving.

vLLM — the production choice. A continuous-batching serving engine that is OpenAI-API-compatible and designed to maximize throughput on GPUs. This is what I reach for the moment an app goes behind an endpoint that real users hit. PagedAttention keeps the GPU busy, and the API surface means your existing OpenAI client code does not change.

Text Generation Inference (TGI) — Hugging Face's serving stack. Also excellent, also OpenAI-compatible, a reasonable alternative to vLLM. I choose between them based on which has better support for the specific model and quantization I am running that week; they are close enough that your choice of one over the other rarely determines success.

TensorRT-LLM / DeepSpeed — for the teams with the engineering time to squeeze the last bit of performance and the models that benefit from it. If you do not have a full-time inference engineer, you do not need these.

The Hardware Math

Let me give you the numbers I actually use, because every tutorial says "you need a good GPU" and then stops. The math is simple: a model needs roughly its parameter count multiplied by the bytes per weight, plus the KV cache for concurrency.

FP16: 2 bytes per parameter. A 7B model needs ~14 GB of VRAM just for weights.
INT8 (AWQ or GPTQ): 1 byte per parameter. 7B → ~7 GB.
4-bit quantization (GGUF Q4): ~0.5 bytes per parameter. 7B → ~4 GB; a 70B → ~40 GB.

So a single 24 GB RTX 4090 comfortably serves a 14B model in FP16 or a 70B model in 4-bit. Two 4090s handle a 70B with room for a real KV cache. One 48 GB workstation card or an A100 80 GB gives you frontier-tier headroom. A Mac with 64–128 GB of unified memory runs 70B-class GGUF models through llama.cpp with surprising grace — slower than a GPU, but silent and quiet in an office in a way two GPUs blasting in a rack never are.

The rule of thumb I give clients: the KV cache is the part people forget. Two users asking long questions can double your memory usage. Size your server for your concurrency, not for one benchmark prompt. I have seen a perfectly tuned single-user demo fall over at five concurrent users because the cache had nowhere to go.

A Production Deployment (vLLM)

Here is the deployment pattern I have shipped most often. On the GPU server, install vLLM and pull the model:

pip install vllm

vllm serve Qwen/Qwen2.5-32B-Instruct-AWQ \
  --host 0.0.0.0 --port 8000 \
  --max-model-len 32768 \
  --quantization awq \
  --gpu-memory-utilization 0.92

A few choices worth explaining:

The AWQ variant. Quantized to 4-bit at the model level, so a 32B model fits comfortably on one 24 GB GPU with room for the KV cache. Quality loss on real tasks is small, and I measure it before shipping rather than assuming it.
--gpu-memory-utilization 0.92. Leave a sliver of VRAM for the CUDA runtime and the context buffers. Setting it to 1.0 is how you get OOM crashes at the worst possible moment.
--max-model-len 32768. This is the ceiling of your context window, and it directly sets KV-cache memory. Do not default to the model's maximum; set what your application actually needs and your concurrency will thank you.

That command gives you an OpenAI-compatible endpoint at http://localhost:8000/v1. Your application code does not change:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed",  # vLLM is unauthenticated by default
)

resp = client.chat.completions.create(
    model="Qwen/Qwen2.5-32B-Instruct-AWQ",
    messages=[
        {"role": "system", "content": "You summarize internal support tickets."},
        {"role": "user", "content": "Summarize this ticket: ..."},
    ],
    temperature=0.2,
)
print(resp.choices[0].message.content)

The api_key line is the sneaky detail — your existing code that hardcodes OPENAI_API_KEY keeps working against a local server. That compatibility is exactly why vLLM is my default: migration from a hosted API becomes a one-line base_url change.

Production Reality: What Goes Wrong

Self-hosting is not "free AI." It is a new production system with its own failure modes. The list, in order of how much they have cost me:

The demo dies under concurrency. Single-user latency looks great; five users queue. The cause is almost always KV-cache memory or the serving engine not batching. Fix: set --max-model-len to what you need, add a second GPU if the cache is the constraint, and load-test with your real prompt lengths before day one.
Quantization quality is assumed, not measured. You save 75% of VRAM with Q4 and never check whether the model still does your task. Fix: build a 50-question eval set, run it on FP16 and Q4, and compare. I have shipped models where the answer was identical on 95% of questions — and I have found tasks (exact number extraction is a classic) where quantization quietly breaks them.
Model changes are not versioned. Someone runs ollama pull latest and the "same model" suddenly behaves differently in production. Fix: pin exact model and quantization versions, store them in your config, and treat model upgrades like any other breaking deploy.
The GPU is idle at night and hot at noon. If your traffic is spiky, you are paying for idle silicon and burning electricity. Fix: size for your 95th percentile, put a load-balancing layer in front, and if your peaks are rare, honestly compare against a hosted option for the overflow.
Nobody owns the stack. A self-hosted model is a server. It needs patching, backups, monitoring, and a person on call. The team that says "we self-host to save money" and has no one who understands the box usually ends up paying more in emergency engineering than they saved in API bills.
Embedding models get forgotten. Your LLM is self-hosted, but if your RAG pipeline still embeds with an external API, you have not actually achieved data sovereignty. Self-host your embedding model too — the same vLLM server can serve it.

When NOT to Self-Host

The honest boundary, stated so you can check yourself:

Spiky, unpredictable traffic. A hosted API scales to zero when you are idle and to a thousand when you are viral. A GPU does not. If your peak-to-average ratio is wild, self-hosting is a cost problem you did not need.
You need the absolute state of the art. The biggest closed models are ahead of open weights on the hardest tasks. If the task quality is the constraint, that gap decides it.
You have no one to run the box. If this is a side project and the hardware is the "fun part," fine. If it is a business workload and the person who deployed it is the only one who understands it, you have a single point of failure wearing a T-shirt.
Small volume, one-off jobs. For a few thousand tokens a month, the setup effort alone exceeds the API bill. Do the math with your own number before you buy.

The Practitioner's Checklist

Before you call a self-hosted deployment done:

[ ] You wrote down the compliance or cost reason — and it is a real one, not fashion
[ ] The model tier matches the task; you did not buy a 70B to extract dates from invoices
[ ] VRAM is sized for weights plus KV cache at your real concurrency, not one benchmark prompt
[ ] Quantization is chosen and validated against your own 50-question eval set
[ ] Model and quantization versions are pinned, not "latest"
[ ] The endpoint is OpenAI-compatible so app code migrates with a one-line change
[ ] Embeddings are self-hosted too if data sovereignty is the actual goal
[ ] Load-testing was done with real prompt lengths and real concurrency
[ ] Monitoring exists: latency, throughput, VRAM, and error rate
[ ] A named person owns patching, backups, and the on-call rotation
[ ] You have a written fallback to a hosted API if the box dies or the demand spikes

The Bottom Line

The compliance-banned fintech client now runs a 32B Qwen model on one 24 GB GPU, serving the whole company, with the data never leaving the building. Their monthly bill for the box is a fixed number they can budget for; the API they replaced would have been metered and unpredictable. That is the real value of self-hosting — not just cheaper tokens, but ownership.

Start where I start: pick the smallest model that does the job, serve it with Ollama to prove the workflow, move to vLLM when real users show up, and write your own cost math before you buy a single GPU. The models will keep improving; the pattern will not.

*Gulshan Yad

Biometric Authentication (Face ID + Fingerprint) in Flutter

Gulshan Yadav — Thu, 27 Aug 2026 13:30:00 +0000

So, in this article, I will be showing you how you can add biometric authentication — Face ID and fingerprint — to your Flutter app using the local_auth plugin.

This is one of the most common requests I get from mobile clients, and for good reason: a login screen with a fingerprint is expected in any finance, health, or messaging app today. I have shipped this exact flow into production apps, and it is simpler than most people expect — and it hides a handful of platform-specific traps that will silently break your build if you skip the setup steps.

For this purpose, we need to add these dependencies in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  local_auth: ^2.2.0
  flutter_secure_storage: ^9.2.0

local_auth is the official plugin that talks to the platform's biometric APIs — Touch ID, Face ID, and Android's fingerprint and face unlock.
flutter_secure_storage stores the auth token securely after the user authenticates, so you never keep credentials in plain text.

Let's jump into the coding part.

Step 1: Platform Setup (This Is Where Most Builds Break)

Before you write a single line of Dart, you must configure both platforms. Skip this and the plugin will throw at runtime, or in some cases at compile time.

Android. Add these permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC" />

For devices running Android 9 or lower you should also keep:

<uses-permission android:name="android.permission.USE_FINGERPRINT" />

iOS. Face ID requires a usage description, otherwise iOS terminates your app when the prompt appears. Add this to ios/Runner/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Unlock your account using Face ID.</string>

That single missing key is the #1 cause of "my biometric app crashes on iPhone" reports. Xcode will not warn you; it will just kill the app at runtime.

Step 2: Check What the Device Actually Supports

You should never assume a device has biometrics. Emulators usually have none, some Android devices have none, and some users disable it in settings. Always check first, then fail gracefully.

import 'package:local_auth/local_auth.dart';

final LocalAuthentication _auth = LocalAuthentication();

Future<bool> canUseBiometrics() async {
  bool isSupported = await _auth.isDeviceSupported();
  bool hasEnrolled = await _auth.canCheckBiometrics;
  return isSupported && hasEnrolled;
}

isDeviceSupported() returns true if the device has any biometric hardware.
canCheckBiometrics returns true if the user has actually enrolled a fingerprint or face. A device can support biometrics while the user has enrolled nothing — and your button should not light up in that case.

Step 3: Authenticate

Now the actual authentication. The key detail here is localizedReason: on iOS this is the sentence shown in the Face ID prompt, and on some Android versions it is required or the call fails.

Future<bool> authenticate() async {
  bool authenticated = false;
  try {
    authenticated = await _auth.authenticate(
      localizedReason: 'Authenticate to access your account',
      options: const AuthenticationOptions(
        biometricOnly: false,
        stickyAuth: true,
      ),
    );
  } catch (e) {
    // Platform errors, app switches, or user-cancelled.
    return false;
  }
  return authenticated;
}

Two options worth understanding:

biometricOnly: false means the user can also authenticate with their device passcode as a fallback when the fingerprint reader fails. For most apps you want this — a locked-out user is worse than a slightly less "pure" biometric login.
stickyAuth: true keeps the authentication valid if the app goes to the background mid-prompt. If you are running on iOS and the user is nudged into another app for a step, this prevents the flow from dying.

Step 4: Store the Session Token Securely

Biometric authentication proves the user is who they say they are, but you still need something to hold the session. Never keep it in SharedPreferences — store it in the secure enclave-backed storage:

import 'package:flutter_secure_storage/flutter_secure_storage.dart';

const FlutterSecureStorage _storage = FlutterSecureStorage();

Future<void> onBiometricSuccess(String token) async {
  await _storage.write(key: 'auth_token', value: token);
}

Future<String?> getStoredToken() async {
  return await _storage.read(key: 'auth_token');
}

The pattern that works in production: on first login ask for the password, get a token from your backend, and store it in secure storage. On every later launch, offer the biometric button — if the fingerprint or face matches, read the token from secure storage and restore the session without the user ever typing a password again.

Step 5: The Login Screen That Ties It Together

Here is the full pattern wired into a widget, the way I would actually ship it. A "Sign in with biometrics" button that only appears when the device can actually do it:

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

  @override
  State<LoginScreen> createState() => _LoginScreenState();
}

class _LoginScreenState extends State<LoginScreen> {
  bool _hasBiometrics = false;
  bool _busy = false;

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

  Future<void> _loadCapability() async {
    final bool available = await canUseBiometrics();
    if (!mounted) return;
    setState(() => _hasBiometrics = available);
  }

  Future<void> _onBiometricLogin() async {
    setState(() => _busy = true);
    final bool ok = await authenticate();
    if (!ok) {
      if (mounted) {
        setState(() => _busy = false);
        // Show password fallback; do not show an error toast for a cancel.
      }
      return;
    }

    // Biometric match: restore the stored session token and enter the app.
    final String? token = await getStoredToken();
    if (mounted) {
      setState(() => _busy = false);
      if (token != null) {
        Navigator.pushReplacement(context,
            MaterialPageRoute(builder: (_) => const HomeScreen()));
      } else {
        // No stored token — full login required this time.
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Sign in')),
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            if (_hasBiometrics && !_busy)
              FilledButton.icon(
                onPressed: _onBiometricLogin,
                icon: const Icon(Icons.fingerprint),
                label: const Text('Unlock with biometrics'),
              )
            else if (_busy)
              const CircularProgressIndicator(),
            TextButton(
              onPressed: () {/* full password flow */},
              child: const Text('Use password instead'),
            ),
          ],
        ),
      ),
    );
  }
}

Two details in this widget are worth copying, not retyping:

The button is conditional. _hasBiometrics is loaded before the button is ever shown. A user on a device with no enrolled biometrics never sees a button that cannot work — that alone removes a whole class of "the fingerprint button does nothing" reviews.
The cancel case is not an error. A user who taps away from the Face ID prompt is back in the UI with the password path visible, not staring at a failure message. That is the difference between a flow users trust and one they abandon.

Important Notes

Here are the things that will bite you in production, in the order I have seen them:

Test on a real device. Biometrics do not work reliably on emulators and simulators. iOS Simulator can fake Face ID via Features → Face ID → Matching Enrolled Face, but Android emulators frequently report nothing enrolled. Your CI and your QA both need a physical device in the rotation, or you will ship a login flow you have never actually exercised.
Handle the cancel case explicitly. When the user taps "Cancel" in the Face ID dialog, local_auth throws PlatformException with code NotAuthenticated. Swallow it and show your password fallback. What you must not do is show a generic error toast — a user who simply changed their mind is the most common event in the entire flow.
biometricOnly: true is rarely what you want. Without a passcode fallback, a user whose fingerprint reader has been blocked (iOS locks it after several failed attempts) is completely locked out of your app until they reboot and re-enter their passcode. On a finance app, that is a support ticket. Use the fallback.
Biometrics can be revoked. If the user deletes a fingerprint or face after enrolling, the OS handles the prompt, but your stored session token is still valid. On a sensitive app, re-check canCheckBiometrics before critical actions — not just at login — so an account whose device auth was removed still gets re-verified for high-value transactions.
Do not use biometrics as your only security layer. The fingerprint proves the device holder's identity on that device; it does not prove much about anything else. Real apps pair it with a server-issued token that has its own expiry, and revoke that token server-side on suspicious activity. The client-side biometric is the front door, not the safe.
Enrollment can change while your app is backgrounded. If the user re-enrolls their fingerprints in Settings and returns to your app, iOS may consider the old authentication stale. If your app supports critical actions, re-run authenticate for those actions rather than trusting a login that happened an hour ago.
Know your platform's error codes. Android 11+ and iOS both return specific errors for hardware-not-present, hardware-unavailable, and lockout states. Log them and map them to user messages — "Biometrics unavailable, use your passcode" is honest; "Unknown error" is not.

Alternative Approaches

If local_auth does not fit, two other roads exist:

Package that wraps native SDKs — some enterprise clients want the bank-grade wrappers that vendor SDKs provide. They add native code, so you are now maintaining platform channels instead of just a plugin, and you should have a concrete compliance reason before choosing this path.
Platform channels for bespoke flows — when you need liveness detection or a custom enrollment UI that the plugin does not expose, you drop to native Kotlin/Swift and call back into Dart. This is real work, and you should only take it when a client's requirements genuinely exceed what local_auth offers.

The default answer for 95% of apps is local_auth. It is maintained, null-safe, covers Face ID, Touch ID, and Android fingerprint and face unlock, and it keeps all the messy native code behind one clean Dart API.

A Quick FAQ

Does this work on the iOS Simulator? Only for Face ID, and only if you use the Features → Face ID → Matching Enrolled Face menu item. Android emulators generally report no enrolled biometrics, so assume the happy path only works on physical hardware.

Does Touch ID still need the usage description? No — NSFaceIDUsageDescription is required for Face ID specifically. But if you only support Touch ID and later add Face ID, iOS will crash at runtime until the key is added, so add it up front.

What if the user has no passcode set at all? Then biometrics cannot enroll, and canCheckBiometrics returns false. Your fallback button handles this automatically because it checks capability before rendering.

That's it — a complete biometric authentication flow in Flutter. Platform setup, capability checks, the authenticate call, a secure place for the session token, and a login screen that only offers biometrics to devices that can actually use them.

I have also written about secure storage, secure text fields, and app-locking patterns — comment below with your own use case and I'll cover it next.

*Gulshan Yad

Why Vector Databases Are Critical for RAG Systems

Gulshan Yadav — Thu, 27 Aug 2026 02:30:00 +0000

A practical look at the retrieval layer of RAG — what a vector database actually does, why keyword search fails, and what it costs to get it wrong.

A few weeks ago, a health-tech client sent me a screenshot that made me stop typing. His RAG system had answered a doctor's question about a medication interaction with a dosing suggestion that was wrong — not subtly wrong, dangerously wrong. The team's first instinct was to blame the model. I asked one question: "How is your system retrieving the context?" Nobody knew. We opened the code and found it: keyword search over their knowledge base, feeding the top hits into the prompt. There was no vector database anywhere in the pipeline.

That answer explained everything. The model had done its job. It read three irrelevant chunks and produced a confident, grounded-sounding, completely wrong answer. The retrieval was broken — there was no way for it to find meaning, only matching strings.

That incident is why I am writing this. Vector databases are not a trendy accessory you bolt onto an LLM project. They are the difference between a RAG system that quotes the right source and one that confidently quotes the wrong one. This article covers what a vector database actually does under the hood, the taxonomy of options, a production architecture, real code, and the honest failure modes — including when you should not use one at all.## The Problem Keyword Search Can't Solve

To understand why vector databases exist, you have to understand the exact failure that killed my client's system. Keyword search — BM25, SQL LIKE, Elasticsearch — matches exact strings. It is brilliant at that, and terrible at meaning.

Consider two sentences:

"The doctor recommended a lower dose for patients with impaired kidney function."
"Renal patients should receive a reduced amount."

Keyword search sees almost no shared tokens between them — "lower" and "reduced" match, nothing else does — so it scores them as near-total strangers and drops the chunk that actually contains the answer. The retrieval layer hands the LLM the wrong documents, and the LLM makes the best of garbage.

The deeper point: in RAG the retrieval step is the source of truth the model is bound to. When the retrieved context is correct, the model will not invent facts it cannot support — but when the context is wrong, it will not know it is wrong either. Retrieval quality sets a hard ceiling on the whole system, and no amount of prompt engineering, fine-tuning, or fancier models raises it. They only make the errors sound more confident.

That is the entire argument for vector databases in one paragraph: search by meaning instead of by exact string.## How Embeddings Actually Work

A vector database stores vectors, and vectors come from embedding models. Here is the mechanism in one paragraph: an embedding model converts a piece of text into a list of numbers — usually 768 to 3,072 floats — arranged so that semantically similar texts land close together in that high-dimensional space. "The dog chased the ball" and "the canine ran after the toy" produce vectors that are nearly parallel, even though they share almost no words. Distance in that space is a proxy for difference in meaning; the famous toy example — king − man + woman ≈ queen — is the same idea in arithmetic form.

The critical practical detail is that the embedding model you use is a permanent architectural decision. You index documents with it, then you query with it. Change the model later and every vector in the store is in the wrong language for the new model — you must re-embed the entire corpus. Decide early, measure the retrieval quality on your own data, and treat the choice as locked-in until you have a hard reason to pay for a re-embed.

What a Vector Database Actually Does

Here is the part that confuses people: the vector database is not doing anything clever with meaning. The embedding model produced the meaning; the database just makes searching it fast and correct. Its job is to solve one specific problem — finding the k nearest neighbors of a query vector among millions of vectors, in milliseconds, at scale.

The Approximate Nearest Neighbor Trade-Off

Finding the exact nearest neighbor in a million-vector space is too slow for real-time retrieval. So vector databases use Approximate Nearest Neighbor (ANN) algorithms that trade a small amount of accuracy for orders of magnitude in speed. The two you will actually meet:

HNSW (Hierarchical Navigable Small World) — a graph-based index. Fast at query time, memory-hungry (the whole graph sits in RAM), excellent for most RAG workloads. This is the default in Qdrant and the go-to choice for most production systems I have built.
IVF (Inverted File) — clusters vectors into partitions and only searches the nearest ones. Uses less memory, slightly slower, better when the index is too large for RAM.

The practical guidance I give clients: start with HNSW — easier to tune, faster to query, and your corpus needs to be very large before memory cost becomes the thing that matters.

Distance Functions Matter

The measure of "near" is configurable, and getting it wrong silently degrades retrieval. The three you will see:

Cosine similarity — measures the angle between vectors, ignores magnitude. The standard default for RAG; most text embeddings behave best with cosine.
Dot product — faster, sensitive to vector magnitude. Fine if your embedding model is normalized; otherwise it rewards long vectors for the wrong reasons.
Euclidean distance — measures raw distance. Works, but more sensitive to scale and less commonly the right default for text.

Rule of thumb: if your embedding model normalizes its output vectors to unit length, dot product and cosine give identical rankings, and dot product is cheaper. If unsure, use cosine.

Metadata Filtering Is the Hidden Requirement

Here is the requirement most tutorials skip and every production system needs: you almost never want to search the whole corpus — you want "all support tickets from the last 90 days" or "policies that apply to the EU region." A vector database that cannot filter by metadata during the ANN search forces you into a classic failure — pulling every matching vector into memory, then doing an exact search over them, which blows your latency budget on a large corpus.

The right approach is index-level filtering: store region, date, document type, tenant ID, and permissions as payload fields, and let the database apply them inside the search. This is also where multi-tenancy lives — one shared store serving ten companies with no tenant filter is an information-leak bug waiting to happen. Filter by tenant, always.

The Vector Database Taxonomy

Every week someone asks me which vector database to use. Here is the landscape as I actually reason about it.

Option	What it is	Best for	Watch out for
Qdrant	Dedicated vector DB, Rust, HNSW-first, metadata filtering first-class	Production RAG, multi-tenant, needs fast filtered search	One more service to operate
pgvector	Postgres extension	Teams already on Postgres, small-to-medium corpora, simplest ops	Filtered search gets slow past a few million vectors
FAISS	Library, not a server (from Meta)	Offline indexing, research, embedding pipelines at scale	You build the persistence, filtering, and serving yourself
Managed (Pinecone, Weaviate Cloud, etc.)	Hosted vector DBs	Teams that want zero ops	Cost grows with volume and latency guarantees vary

The honest advice: if you are already running Postgres and your corpus is under a few million chunks, pgvector is the right first move — one fewer moving part, and your transactions and vectors live in one place. The moment filtered search on a large index starts hurting, or you need predictable multi-tenant latency, move to a dedicated engine like Qdrant. FAISS is for building pipelines, not shipping apps; managed services are for teams whose scarce resource is time, not money.

A Production-Shaped Example

Let me make this concrete. Here is the smallest real architecture I would ship: embed with a good model, store in Qdrant, search with metadata filtering, feed the top chunks to an LLM. I will use the Qdrant client with an OpenAI-compatible embedding endpoint.

First, create the collection with the right distance function and a payload schema that carries metadata:

from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance, PointStruct

client = QdrantClient(url="http://localhost:6333")
COLLECTION = "knowledge_base"

client.recreate_collection(
    collection_name=COLLECTION,
    vectors_config=VectorParams(size=1024, distance=Distance.COSINE),
)

Then index a batch of documents, storing the text alongside its vector so you can return the actual source, not just an ID:

import requests

def embed(text: str) -> list[float]:
    r = requests.post(
        "http://localhost:8000/v1/embeddings",
        json={"model": "your-embedding-model", "input": text},
    )
    return r.json()["data"][0]["embedding"]

docs = [
    {"id": 1, "tenant": "acme", "region": "EU", "text": "Kidney-impaired patients should receive a reduced dose."},
    {"id": 2, "tenant": "acme", "region": "EU", "text": "Standard adult dosing for this compound is 40 mg once daily."},
]

points = [
    PointStruct(
        id=d["id"],
        vector=embed(d["text"]),
        payload={"tenant": d["tenant"], "region": d["region"], "text": d["text"]},
    )
    for d in docs
]
client.upsert(collection_name=COLLECTION, points=points)

Query with the tenant filter applied at the index level, not as an afterthought:

query = "What dose should be used for a patient with reduced kidney function?"

hits = client.search(
    collection_name=COLLECTION,
    query_vector=embed(query),
    query_filter={"must": [{"key": "tenant", "match": {"value": "acme"}}]},
    limit=5,
)

context = "\n\n".join(h.point.payload["text"] for h in hits)
print(context)

That query_filter line keeps tenant A's answers from leaking into tenant B's. It belongs inside the search — the reason you want a database that supports index-level filtering rather than a raw library.

The full RAG call then becomes: embed the user question, retrieve the top-k chunks with the tenant filter, join them into a context block, and send that plus the question to the LLM with an instruction to answer only from the provided context.

Production Reality: Where This Quietly Goes Wrong

I have hit every one of these in real deployments, in the order they hurt:

Chunk size and overlap are treated as defaults. Chunking determines what retrieval can even find. Chunks too large dilute the meaning per vector; too small lose the surrounding context. There is no universal answer — it depends on your documents — so measure it, don't inherit a magic number from a blog post. Start at 512–768 tokens with 10–15% overlap and benchmark.
top-k set once, never revisited. A limit=3 that worked on your demo corpus will starve a production corpus. Monitor how often the correct answer appears in the retrieved set and tune k until retrieval quality stops improving.
No hybrid search, so exact terms get lost. Embeddings are bad at exact strings: part numbers, error codes, model names. A query for "ERR-1042" will return semantically similar-looking noise instead of the document that literally contains "ERR-1042". The fix is hybrid retrieval — run BM25 keyword search and vector search in parallel and merge results with a reciprocal rank fusion.
Re-ranking is skipped for cost reasons. Retrieving 50 candidates and re-ranking the top 20 with a cross-encoder beats just taking the top 5 from vector search. It costs latency and money, and on real user queries it is usually worth it — the single biggest retrieval quality upgrade I can make for a client.
Embedding drift after a model change. Upgrade the embedding model and forget the re-embed, and every query is measured against vectors in a different space. Retrieval silently degrades. Version your embeddings and re-embed before you ship.
The empty-result failure is unhandled. When retrieval returns nothing relevant, many systems still feed an empty or irrelevant context to the model, which then answers from its training data as if grounded. Enforce a minimum relevance threshold and let the system say "I don't have the information" instead of hallucinating.

When NOT to Use a Vector Database

The honest part. A vector database is not always the answer, and I have told clients so to their face:

Your corpus is under a few thousand chunks and does not grow. Run a brute-force cosine scan in a few lines of NumPy over an in-memory list. You do not need a server for that.
Your queries are dominated by exact terms — codes, IDs, SKUs, model numbers. A well-indexed relational table or Elasticsearch beats embeddings there. Add vector search only if you also have meaning-based queries.
You cannot maintain one more service. Every service you add to a small team is a pager rotation, a backup job, and a failure surface. If pgvector covers your volume, do not spin up a second database just to feel modern. ## The Practitioner's Checklist

Before you trust a RAG system, walk this list:

[ ] Retrieval is meaning-based — you have embeddings and a vector index, not keyword search alone
[ ] The embedding model choice is deliberate and versioned; a change triggers a full re-embed
[ ] Distance function matches your embedding model (cosine for most text models)
[ ] Metadata filtering — tenant, region, date, doc type — happens inside the search, not after it
[ ] Multi-tenant isolation is enforced at the index level, never by trusting the app layer
[ ] Chunk size and overlap were tuned against your own eval set, not inherited
[ ] top-k is monitored and tuned, not frozen at the demo value
[ ] Exact-term queries are covered — hybrid search or a keyword fallback exists
[ ] Retrieval is re-ranked if quality or budget allows; you measured the trade-off
[ ] Empty retrieval is handled explicitly — the system says "I don't know" instead of hallucinating
[ ] Retrieval quality has an evaluation set and a measured metric

The Grounded Systems Are Built on Retrieval

Back to the health-tech client. We replaced the keyword layer with a vector store, added metadata filters so each hospital's data stayed isolated, tuned chunking against their real documents, and re-ranked the top candidates. The wrong-dosage answers stopped because retrieval started returning the right source. We changed the model nowhere and almost nothing about the prompt — the fix was entirely in the retrieval layer.

That is the whole lesson, and I will repeat it every time someone blames the LLM: in RAG, the model is only as good as the context you hand it, and the context is only as good as retrieval. Build the retrieval layer well — it is the difference between sounding grounded and being grounded.

Start small: get your documents into a vector index, add the tenant filter, and benchmark before you buy a second server. The day a wrong chunk reaches a clinician, the vector database was never a convenience — it was the floor.

*Gulshan Yad

Flutter Push Notifications with FCM — Complete 2026 Walkthrough

Gulshan Yadav — Wed, 26 Aug 2026 13:30:00 +0000

Every project I touch eventually needs push notifications, and every project asks the same question: why does the notification work in the foreground but vanish in the background? So, in this article, I will be showing you how you can set up Flutter push notifications with Firebase Cloud Messaging (FCM) the complete way — foreground, background, and terminated states — including the 2026 gotchas: the Android 13 runtime permission, the FCM HTTP v1 API, and the background handler that half the tutorials skip.

For this purpose, we need to add these dependencies in your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  firebase_core: ^3.8.0
  firebase_messaging: ^15.1.0
  flutter_local_notifications: ^18.0.0

firebase_core initializes Firebase in your app — mandatory first step.
firebase_messaging handles receiving FCM messages and the device token.
flutter_local_notifications shows notifications for messages received while the app is in the foreground — a step everyone forgets, because FCM does not display foreground messages by default.

The firebase_messaging package's own documentation points you to flutter_local_notifications for exactly this reason, and skipping it is the #1 cause of "notifications work when the app is closed but not when I open it."

Let's jump into the coding part.

Step 1: Firebase Project Setup

Before any Dart, the project-side setup, because it is where most people stall:

Create a Firebase project in the Firebase console and add your Android (package name) and iOS (bundle ID) apps.
Download google-services.json and drop it into android/app/, and GoogleService-Info.plist into ios/Runner/.
Add the Google services Gradle plugin to android/build.gradle:

// android/build.gradle
buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.4.2'
  }
}

and apply it at the bottom of android/app/build.gradle:

apply plugin: 'com.google.gms.google-services'

For iOS, update your AppDelegate to let Flutter know the app is done launching (needed for background notifications):

// ios/Runner/AppDelegate.swift
import FirebaseCore

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(_ application: UIApplication,
                            didFinishLaunchingWithOptions launchOptions:
                            [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    FirebaseApp.configure()
    if #available(iOS 10.0, *) {
      UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate
    }
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

On iOS you must also upload your APNs key to Firebase (Project settings → Cloud Messaging) or FCM cannot deliver to iPhones. This is the most common silent failure: everything works on Android, nothing arrives on iOS, and the reason is a missing APNs key.

Step 2: Initialize Firebase and Request Permission

Now the Dart side. Initialize Firebase before anything else, request notification permission, and grab the device token:

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

Future<void> setupPush() async {
  await Firebase.initializeApp();
  final messaging = FirebaseMessaging.instance;

  // Android 13+ requires a runtime permission (API 33+)
  final settings = await messaging.requestPermission(
    alert: true, badge: true, sound: true,
  );
  debugPrint('Granted: ${settings.authorizationStatus}');

  // Register for remote messages (needed on iOS too)
  await messaging.setForegroundNotificationPresentationOptions(
    alert: true, badge: true, sound: true,
  );

  // Get the device token to send to your backend
  final token = await messaging.getToken();
  // Send `token` to your server and store it.
  debugPrint('FCM Token: $token');
}

On Android 13 and newer, requestPermission() triggers the runtime dialog the OS requires — without it, notifications are silently blocked. On older Android and on iOS, this maps to the appropriate system permission. Run this in main() after WidgetsFlutterBinding.ensureInitialized().

Step 3: The Foreground Message Handler

FCM does not show a notification when the app is in the foreground — it only delivers the data to your handler. So we forward it to flutter_local_notifications:

import 'package:flutter_local_notifications/flutter_local_notifications.dart';

final _local = FlutterLocalNotificationsPlugin();

Future<void> initLocalNotifications() async {
  const init = InitializationSettings(
    android: AndroidInitializationSettings('@mipmap/ic_launcher'),
    iOS: DarwinInitializationSettings(),
  );
  await _local.initialize(init);
}

Future<void> showForegroundNotification(RemoteMessage message) async {
  await _local.show(
    message.hashCode,
    message.notification?.title ?? 'Update',
    message.notification?.body ?? '',
    const NotificationDetails(
      android: AndroidNotificationDetails(
        'main_channel', 'General',
        channelDescription: 'General notifications',
        importance: Importance.high,
        priority: Priority.high,
      ),
      iOS: DarwinNotificationDetails(),
    ),
  );
}

Then, in your setup, listen for foreground messages and route them:

FirebaseMessaging.onMessage.listen(showForegroundNotification);

Step 4: The Background and Terminated-State Handler

This is the part that gets skipped, and it is why notifications "disappear" when the app is closed. A message that arrives when the app is backgrounded or terminated is delivered to a top-level handler — a function outside your widget tree, exactly like the workmanager callback in my background-tasks guide:

@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  // Do NOT touch UI here. Log, or queue work.
  debugPrint('Background message: ${message.notification?.title}');
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);
  runApp(const MyApp());
}

The @pragma('vm:entry-point') annotation is essential — without it, release builds can strip the handler and background messages silently do nothing. When the app is terminated, the OS launches a minimal isolate to run this handler; it has a few seconds and no UI access. If you need to handle taps that open the app, listen to FirebaseMessaging.onMessageOpenedApp and handle messaging.getInitialMessage() for terminated-state launches.

Step 5: Sending a Notification — the 2026 Way

In 2026, send using FCM's HTTP v1 API (the legacy send endpoint is deprecated). Example using the legacy-free approach with a server service account:

# Server side — use an OAuth2 token from your service account
curl -X POST "https://fcm.googleapis.com/v1/projects/<YOUR_PROJECT_ID>/messages:send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "token": "<DEVICE_FCM_TOKEN>",
      "notification": {
        "title": "Order shipped",
        "body": "Your order #4821 is on the way"
      },
      "android": { "notification": { "channel_id": "main_channel" } }
    }
  }'

Two things matter here. First, the android.notification.channel_id must match the channel name from your AndroidNotificationDetails — mismatch means the notification arrives with the app's default channel and bad behavior. Second, for Android 13+ you can include android.notification.priority and rely on the channel importance you set in the app, not the payload.

Important Notes — The Failure Modes I Have Paid For

Foreground messages are never shown by FCM. If you did not wire onMessage into flutter_local_notifications, foreground notifications appear to be "broken." They are not broken — they are being delivered to a handler that does nothing.
Android 13 blocks notifications without the runtime permission. Test on a physical Android 13+ device, not an emulator. If requestPermission() returns denied, no notification will ever show, and no amount of payload tuning fixes it.
The background handler must be top-level with @pragma('vm:entry-point'). A closure that references widget state will crash or no-op in the background isolate.
Token refresh. FCM tokens rotate. Listen to messaging.onTokenRefresh and update your backend, or users quietly stop receiving notifications after a reinstall.
iOS needs the APNs key configured in Firebase, or Android works and iOS is dead silent. Also register the background modes in your Xcode project if you need data-only messages.
Do not trust the emulator for delivery. Emulators often have unreliable FCM delivery. Physical devices behave differently; test there.
Keep notification payloads small. A 4KB notification payload is the FCM limit. If you need to send rich data, send an ID and fetch the rest over your API when the notification is tapped.

Step 6: Handle Token Refresh and Notification Taps

Two pieces of the wiring complete the picture, and both are usually missing from tutorials.

Token refresh. FCM tokens rotate — after a reinstall, an app update, or on some OS quirks. Listen for it and push the new token to your backend, or your users silently stop getting notifications:

FirebaseMessaging.instance.onTokenRefresh.listen((newToken) {
  // Send newToken to your backend, replacing the old one.
  debugPrint('Token refreshed: $newToken');
});

Tap handling with navigation. When the user taps a notification you usually want to deep-link somewhere. The message payload's data map is where you put a route or ID, and you handle taps in the foreground and the backgrounded/terminated states separately:

void setupTapHandlers() {
  // App was in foreground when tapped
  FirebaseMessaging.onMessageOpenedApp.listen((message) {
    final route = message.data['route'];
    navigatorKey.currentState?.pushNamed(route ?? '/');
  });

  // App was terminated when tapped — check on launch
  FirebaseMessaging.instance.getInitialMessage().then((message) {
    if (message != null) {
      final route = message.data['route'];
      navigatorKey.currentState?.pushNamed(route ?? '/');
    }
  });
}

Keep a GlobalKey<NavigatorState> at the app root so the handler can navigate even when it runs outside a widget's context. Data messages (a data field without a notification field) are the reliable way to carry this routing payload, because FCM delivers them to your handler on every state — foreground, background, and terminated.

Step 7: Subscribing to Topics

Instead of sending to individual device tokens, FCM supports topics — one message fans out to every subscribed device. This is how I shipped a weekly digest for a client without managing a token list:

await FirebaseMessaging.instance.subscribeToTopic('digest-weekly');
await FirebaseMessaging.instance.unsubscribeFromTopic('digest-weekly');

Send to a topic with the same HTTP v1 endpoint, replacing "token" with "topic": "digest-weekly". Topics are perfect for broadcast-style notifications (news, offers, digests) and dead simple at scale. The catch: everyone subscribed to a topic gets the same message, so personalization still needs a token-based send.

The 2026 Checklist — Go Through This Before You Ship

[ ] google-services.json in android/app/ and Gradle plugin applied
[ ] iOS: GoogleService-Info.plist in ios/Runner/, APNs key uploaded in Firebase
[ ] iOS: FirebaseApp.configure() in AppDelegate, notification delegate set
[ ] Android 13+ runtime permission requested and granted on a physical device
[ ] Foreground messages routed through flutter_local_notifications
[ ] Top-level background handler with @pragma('vm:entry-point')
[ ] onMessageOpenedApp + getInitialMessage handle taps in every state
[ ] onTokenRefresh updates your backend
[ ] Payload data carries a route key, tested on a locked, backgrounded device
[ ] Sends use the FCM HTTP v1 API, not the deprecated legacy endpoint

Data-Only Messages vs Notification Messages — Pick Deliberately

FCM has two message shapes, and choosing wrong is the root of half the "notification disappeared" bugs I debug.

A notification message (a notification field) is handled by the OS when the app is backgrounded or terminated — FCM itself builds the notification, and your Dart handler is not guaranteed to run for display purposes. A data-only message (only a data field, no notification) is delivered to your Dart handler in every state — foreground, background, and terminated — and you decide what to show, or whether to show anything.

My rule: use notification messages for simple alerts you want the OS to display with zero code, and data-only messages whenever you need custom behavior — routing, localization, deciding on-device whether the notification is relevant. The tap-handling code above relies on data, so if you only ever send notification messages, you will have nothing to read in onMessageOpenedApp. When in doubt, send both: a small notification for OS display plus a data payload with your routing keys.

For quick manual tests, the Firebase console's Cloud Messaging section lets you compose and send a message without writing any server code — target your physical device by token and confirm each state (foreground, background, terminated) before you involve the backend. That ten-minute manual pass has caught more misconfiguration for me than any amount of code reading, because it isolates the problem: if the console send fails to display, the bug is in your app wiring; if it displays but your API send does not, the bug is server-side.

That's it — a complete FCM push notification integration for 2026: Firebase project setup, Android 13 permission, device token, foreground routing through local notifications, the top-level background handler, and a working HTTP v1 send. The four-file checklist is: google-services.json, the Gradle plugin, the iOS AppDelegate, and the main.dart wiring — and the background handler is the one that makes the difference between "works on my desk" and "works on a locked phone in a pocket."

I have also covered local scheduled notifications and background tasks with this exact stack — comment below with the notification feature you are stuck on and I'll cover it next.

*Gulshan Yad