DEV Community: Samuel Adekunle

[Boost]

Samuel Adekunle — Fri, 18 Sep 2026 12:26:43 +0000

Samuel Adekunle

Sep 18

AI Agent Skills: Everything You Need to Know

#ai #skills #techwithsam #aiagents

6 min read

AI Agent Skills: Everything You Need to Know

Samuel Adekunle — Fri, 18 Sep 2026 12:25:34 +0000

In 2024, AI coding agents (Claude, Cursor, Copilot, etc.) became capable enough to do real work. Teams started writing long instruction files and system prompts. But there was no standard way to package, share, or discover them. Every team reinvented the wheel.

Today, we’re creating a complete handbook on how the solution to the issue above came about, how to use it, and how it became one of the most useful things in AI right now: Agent Skills and the platform that makes them easy to use — skills.sh.

By the end of this workflow, you will understand:

What Agent Skills actually are
How skills.sh works
How to install and use great existing skills
How to create your own skills from scratch
How to share them with your team or the world
And the best practices so your skills actually get used

This is not Flutter-only. The same system works whether you write Flutter, React, backend code, DevOps, or even content. I’ll use Flutter as one practical example, but everything here is flexible.

Let’s get into it.

What are Agent Skills and skills.sh?

An Agent Skill is a lightweight, open format for giving AI agents specialized knowledge and workflows. At its core, a skill is just a folder that contains a file called SKILL.md.

Here’s the basic structure:

my-skill/
├── SKILL.md          ← Required
├── scripts/          ← Optional
├── references/       ← Optional
└── assets/           ← Optional

The SKILL.md file has two parts:

YAML frontmatter at the top (name + description)
Markdown instructions below

The description is extremely important. Agents only load the name and description of every skill at startup. When your request matches a skill’s description, the agent then loads the full instructions. This is called progressive disclosure — it keeps the context window clean even if you have dozens of skills installed.

Now, what is skills.sh?

skills.sh is the open directory and CLI for the Agent Skills ecosystem. Think of it as the npm for AI agent capabilities. It was built by Vercel Labs and works across many agents, including Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI, and more.

You install skills with a single command:

npx skills add owner/repo

That’s it. The CLI detects which agents you have and installs the skill in the right place.

You can browse popular skills on skills.sh, see a leaderboard, and discover what the community is building.

Discover on skills.sh

Community leaderboard sorted by installs
Browse by category, language, or use case
Official skills from Anthropic, Vercel, and more

Demo of some great skills

Let me show you how this looks in practice.

First, installing a skill is simple; run: npx skills add vercel-labs/agent-skills

Note: You need to have Node.js installed on your machine; download and install it.

You can also install any public repo that contains skills.

Once installed, the agent can automatically use them when relevant.

Here are four strong examples of skills.

Example 1 — PR Review (universal)

---
name: pr-review
description: "Reviews pull requests for bugs, security issues, code quality, and adherence to best practices. Use when the user asks to review a PR, check a diff, or get feedback before merging."
---

This one works on any codebase.

Example 2 — Flutter Widget Test (our case study)

---
name: flutter-widget-test
description: Generates high-quality Flutter widget tests following best practices. Use when the user asks to write tests for a Flutter widget, create widget tests, or improve test coverage for UI components.
---

This shows how you can encode framework-specific knowledge.

Example 3 — Generate Changelog

---
name: generate-changelog
description: Generates clean, professional changelog entries or release notes from git commits or PR descriptions. Use when the user asks for a changelog, release notes, or version summary.
---

Super practical for any project.

Example 4 — Brand Voice (non-code example)

---
name: brand-voice
description: Writes content following a consistent professional brand voice. Use when creating LinkedIn posts, Twitter/X threads, blog intros, product announcements, or any marketing copy.
---

This proves skills are not only for code. You can package writing style, design systems, internal processes — anything repeatable.

Build your own skill

This is the most important part of the workflow.

Creating a skill is straightforward.

Step 1: Create a folder and the required file

mkdir my-skill
touch my-skill/SKILL.md

Step 2: Write the frontmatter

The two required fields are name and description.

The description is what the agent uses to decide whether to activate the skill. Be specific. Include the kind of phrases a real user would say.

---
name: my-skill-name
description: What it does and when to use it.
Include real trigger phrases here.
---

Step 3: Write clear instructions

Good structure usually includes:

When to use this skill
When not to use it
Step-by-step process the agent should follow
Expected output format
Any edge cases or rules

Write it like you’re explaining it to a smart new teammate.

Step 4: Test with real prompts

Install locally with npx skills add ./my-skill then trigger it with exact phrases. If it doesn't activate, the description needs to be more specific.

Key tips while creating:

Start small. A focused 15–30 line skill is better than a long vague one.
Make the description do the heavy lifting for activation.
Write instructions the way you would explain the task to a smart junior developer.
Test it immediately after creating it.

Once you’re happy with it, you can install it locally and start using it right away.

Share your skills

You have two main ways to share.

1. With your team / private

Just commit the skills folder into your repository. Everyone who clones the project gets the skills.

2. Publicly with skills.sh

Push the skill to a public GitHub repository. You have two common structures:

Dedicated repo → SKILL.md sits at the root
Multi-skill repo → skills live in subfolders

# Single skill
my-repo/
└── SKILL.md

# Multi-skill
my-repo/
├── pr-review/
│ └── SKILL.md
└── changelog/
└── SKILL.md

Then anyone can install it with:

# Public: single-skill repo
npx skills add your-username/my-skill

or target a specific skill:

# Public: multi-skill repo 
npx skills add you/repo --skill name

You can also add the skills.sh badge to your README so people can see install counts.

Clear name + excellent description = more people will find and use your skill.

Best Practices

Here are the practices that separate good skills from great ones:

Write trigger-friendly descriptions — this is the #1 factor for reliable activation.
Keep skills focused — one clear job per skill. Compose multiple skills instead of making one giant skill.
Use progressive disclosure properly — put long references or examples in separate files.
Document when not to use the skill.
Test with real phrasing — try the exact words your users (or you) would actually type.
Treat skills like code — version them, review them, improve them over time.
Only install skills from sources you trust — always skim the SKILL.md and any scripts.
For teams — store shared skills in the repo so consistency is automatic.

Follow these, and your skills will actually get used instead of sitting unused.

That’s the complete handbook.

You now know:

What Agent Skills are and how progressive disclosure works
What skills.sh is and how to install skills
How to demo and evaluate existing skills
How to create your own
How to share them
And the best practices that make them effective

The biggest shift is this: instead of repeating the same instructions in every chat, you package the knowledge once and let any compatible agent use it.

If you create a skill after reading this, drop the GitHub link in the comments. I’d love to see what you build.

If you found this valuable, hit like, subscribe, and turn on notifications.

I also offer 1-on-1 mentorship if you want help setting up skills or AI workflows for your team — click here.

I’ll see you in the next one. Peace.

[Boost]

Samuel Adekunle — Thu, 10 Sep 2026 22:27:33 +0000

Samuel Adekunle

Sep 10

Automate Flutter Releases with Shorebird + GitHub Actions (Skip App Store Review)

#flutter #mobile #techwithsam #githubactions

6 min read

Automate Flutter Releases with Shorebird + GitHub Actions (Skip App Store Review)

Samuel Adekunle — Thu, 10 Sep 2026 22:27:12 +0000

A real pain point for mobile apps is waiting days or weeks for App Store and Play Store reviews whenever you need to ship a fix or a small update to users.

That exact problem is what we are solving in this article. I’ll show you exactly how to automate your Flutter releases and patches using Shorebird and GitHub Actions, so you can push updates to users in minutes instead of waiting for store review.

We are going to create a clean, production-ready CI pipeline for both full releases and instant code-push updates.

Prerequisites

Before we start, here’s what you need:

A Shorebird account and an app already set up with Shorebird
Shorebird CLI installed and logged in on your machine
A Flutter project that already has Shorebird initialized
A GitHub repository
Basic understanding of GitHub Actions

If you haven’t set up Shorebird in your Flutter app yet, check out my video on YouTube on how to set up Shorebird. This article assumes that’s already done.

Authentication Setup

The first thing we need is authentication so GitHub Actions can talk to Shorebird.

Go to the Shorebird Console → Account → API Keys → Create API Key.

Give it a clear name, e.g “GitHub Actions”, choose an expiration, and set the required permissions.

Copy the key immediately because you won’t see it again.

Now go to your GitHub repository → Settings → Secrets and variables → Actions → New repository secret.

Name it exactly: SHOREBIRD_TOKEN

Paste the key and save.

This token will be available in all your workflows as ${{ secrets.SHOREBIRD_TOKEN }}.

That’s the only authentication step you need.

Official Shorebird GitHub Actions

Shorebird provides three official GitHub Actions that make life much easier:

shorebirdtech/setup-shorebird@v1 — installs Shorebird on the runner
shorebirdtech/shorebird-release@v1 — creates a release
shorebirdtech/shorebird-patch@v1 — creates a patch

I strongly recommend using these instead of calling the CLI manually. They’re cleaner and maintained by the Shorebird team.

Release Workflow

Let’s build the release workflow first.

Create a new file in your project: .github/workflows/shorebird-release.yml

Here’s the structure:

Trigger on version tags: v1.0.0, v1.2.3, etc. or manually trigger the workflow
Set the SHOREBIRD_TOKEN as an environment variable
Pin your Flutter version (very important)
Checkout the code
Set up Java for Android (or Xcode signing for iOS)
Set up Shorebird with caching
Decode your keystore/certificates from secrets
Run the official shorebird-release action
Upload the APK, AAB, or IPA as artifacts

I’ll show both Android and iOS versions.

For Android, the key steps are decoding the keystore and creating the key.properties file from secrets.

GitHub Secrets You Need to Add for Android

Go to GitHub → repo → Settings → Secrets and variables → Actions → New repository secret

Secret name - Value
ANDROID_KEY_ALIAS - your_key_alias
ANDROID_KEY_PASSWORD - your_key_password
ANDROID_STORE_PASSWORD - your_store_password
ANDROID_KEYSTORE_BASE64 - run `base64 -i ~/path/to/upload.jks | tr -d '\n' | pbcopy`
The keystore base64 will be copied to your clipboard; paste it into GitHub Secrets

GitHub Secrets You Need to Add for iOS

Go to GitHub → repo → Settings → Secrets and variables → Actions → New repository secret

Secret name - Value
IOS_CERTIFICATE_BASE64 - base64 of your .p12
IOS_CERTIFICATE_PASSWORD - Password you set when exporting the .p12
IOS_PROVISIONING_PROFILE_BASE64 - base64 of com.example.app profile

For iOS, you need to import the certificate and provisioning profile into a temporary keychain.

# IOS_CERTIFICATE_BASE64 - export your .p12 from Keychain Access first, then:
base64 -i ~/path/to/distribution.p12 | tr -d '\n' | pbcopy

# IOS_PROVISIONING_PROFILE_BASE64 - download from Apple Developer Portal
base64 -i ~/path/to/YourApp_AppStore.mobileprovision | tr -d '\n' | pbcopy

You can check out this document on how to create an Apple Distribution Certificate.

Once this workflow finishes, you get signed artifacts ready to upload to the stores.

This is your normal full release path.

name: Shorebird Release

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Target platform'
        required: true
        default: 'both'
        type: choice
        options:
          - android
          - ios
          - both

jobs:
  release_android:
    name: Release Android
    if: ${{ github.event.inputs.platform == 'android' || github.event.inputs.platform == 'both' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Setup Android Keystore
        run: |
          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 --decode > android/app/keystore.jks
          cat > android/key.properties <<EOF
          storePassword=${{ secrets.ANDROID_STORE_PASSWORD }}
          keyPassword=${{ secrets.ANDROID_KEY_PASSWORD }}
          keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}
          storeFile=keystore.jks
          EOF
        shell: bash

      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1

      - name: Shorebird Release (Android)
        uses: shorebirdtech/shorebird-release@v1
        id: shorebird-release
        with:
          flutter-version: latest
          platform: android
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}

      - name: Print Release Version
        run: echo "Released version ${{ steps.shorebird-release.outputs.release-version }}"
        shell: bash

Full release on GitHub Gist.

Patch Workflow — The Real Power

Now, the part that actually lets you skip App Store review.

Create another file: .github/workflows/shorebird-patch.yml

name: Shorebird Patch

on:
  push:
    branches:
      - main
  workflow_dispatch:
    inputs:
      platform:
        description: 'Target platform'
        required: true
        default: 'both'
        type: choice
        options:
          - android
          - ios
          - both
      release-version:
        description: 'Release version to patch (e.g. 1.0.0+1). Defaults to latest.'
        required: false
        default: 'latest'

jobs:
  patch_android:
    name: Patch Android
    if: ${{ github.event_name == 'push' || github.event.inputs.platform == 'android' || github.event.inputs.platform == 'both' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Setup Android Keystore
        run: |
          echo "${{ secrets.ANDROID_KEYSTORE_BASE64 }}" | base64 --decode > android/app/keystore.jks
          cat > android/key.properties <<EOF
          storePassword=${{ secrets.ANDROID_STORE_PASSWORD }}
          keyPassword=${{ secrets.ANDROID_KEY_PASSWORD }}
          keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}
          storeFile=keystore.jks
          EOF
        shell: bash

      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1

      - name: Shorebird Patch (Android)
        uses: shorebirdtech/shorebird-patch@v1
        id: shorebird-patch
        with:
          platform: android
          release-version: ${{ github.event.inputs.release-version || 'latest' }}
          args: --allow-asset-diffs --allow-native-diffs
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}

      - name: Print Patch Number
        run: echo "Patch number ${{ steps.shorebird-patch.outputs.patch-number }}"
        shell: bash

Full release on GitHub Gist.

Trigger this one on hotfix tags, for example: v1.0.0-hotfix.1

The structure is almost identical to the release workflow, but we use the shorebird-patch action instead.

Important points:

A patch can only be applied to an existing release
Use the — staging flag first so you can preview the update
After testing with shorebird preview — track=staging, promote it to production from the Shorebird Console.

This is the real magic. Users get the fix over-the-air (OTA) in minutes. No waiting for review. No forcing them to download a new version from the store.

Recommended Development Workflow

Here’s the clean workflow I recommend (and the one Shorebird documents):

Work on features and fixes on feature branches
Open a pull request into main
CI runs formatting, analysis, and tests
Squash and merge into main (main stays always releasable)
When you’re ready for a full release → create a tag like v1.2.0 → the release workflow runs automatically
If a critical bug appears → fix it on main → cherry-pick into the release branch → create a hotfix tag like v1.2.0-hotfix.1 → the patch workflow runs
Preview on staging → promote to production

This keeps everything automated, clean, and low-risk.

Best Practices

A few important tips:

Always pin the Flutter version on releases using — flutter-version
Use — dry-run on pull requests so you catch build issues early without creating real releases or patches
Keep your SHOREBIRD_TOKEN secure — never hardcode it
For iOS environments without certificates, you can use — no-codesign (then sign later)
Shorebird automatically runs in non-interactive mode in CI when the token is present

Follow these, and your pipeline will be solid.

Resources

All of this is based on the official Shorebird documentation:

I’m also a Shorebird Ambassador, so if you have questions, drop them in the comments.

That’s it.

You now have a complete automated system:

Full releases go through the stores as usual
Critical updates and bug fixes go live to users in minutes via Shorebird

No more waiting for review every single time.

If this was useful, hit the like button, subscribe, and turn on notifications so you don’t miss the next post.

If you want personalized help setting this up for your project, you can send a DM.

I’ll see you in the next one. Peace.

[Boost]

Samuel Adekunle — Wed, 02 Sep 2026 10:19:00 +0000

Samuel Adekunle

Sep 2

AI Engineering for Flutter Developers - Production AI Engineering in Flutter

#ai #gemini #flutter #techwithsam

3 min read

AI Engineering for Flutter Developers - Production AI Engineering in Flutter

Samuel Adekunle — Wed, 02 Sep 2026 10:18:03 +0000

Over the past three articles, we've gone from fundamentals to building more reliable AI features to creating multi-agent workflows.

But there's still one big gap most tutorials never cover:
"How do you take an AI feature from 'it works on my machine' to something that's actually ready for production?"

That's what this article is all about.

We're focusing on Performance, Privacy, Security, and real-world Best Practices - the things that separate demos from production-grade AI Engineering.

What Production AI Engineering Really Means

Shipping a reliable, safe, and maintainable AI feature is a different skill.

Production AI Engineering means thinking about:

How fast it feels to the user
What data leaves the device
How secure your implementation is
How you handle failures
How you monitor and improve the system over time

We'll walk through the most important considerations every Flutter developer should know before shipping AI features.

Performance Considerations

Users are very sensitive to latency. A slow AI response can make even a smart feature feel broken.

Key things to consider:

On-device vs Cloud trade-offs
When streaming actually helps
Avoiding unnecessary AI calls
Caching results when appropriate
Choosing the right model size for the job

Privacy Best Practices

Not every piece of user data should be sent to an external AI model.

Data Minimization: Send only the minimal text snippet the prompt actually needs. Never dump an entire database record into an LLM call.
Local PII Sanitization: Strip emails, phone numbers, credit-card numbers, and home addresses before sending prompts to external APIs.
On-Device First for Sensitive Data: Health logs, financial notes, and private messages should stay on-device via TFLite or local embedding models.
Explicit User Transparency: Inform users whenever AI processes their input — and provide an opt-out toggle in Settings.

The goal is to make responsible decisions about what data leaves the user's phone.

Security Best Practices

This is an area where many developers make critical mistakes.

1. Pitfall: Committing GEMINI_API_KEY = "AIzaSy…" into lib/api_config.dart
Fix: Pass keys at build time via  --dart-define=GEMINI_API_KEY=…
or store them in server-side environment variables. 

2. Pitfall: Treating user input as trusted when building the prompt.
Fix: Treat user input as untrusted data.
Delimiter: <user_input>…</user_input>  +  enforce JSON Schema outputs.

3. Pitfall: No per-user rate-limiting on the AI endpoint.
Fix: Enforce per-user quota (e.g., 20 AI req / user / hr)
on the backend or Firebase Cloud Functions to stop wallet-depletion attacks.

Reliability, Monitoring & Evaluation

Even with good performance, privacy, and security, your AI feature still needs to be reliable.

Structured Exception Handling: Differentiate rate-limits (HTTP 429), timeouts, safety refusals, and JSON-parse errors with a custom AIException class.
Graceful Fallbacks: If the cloud model fails after retries, drop to a cached result or an on-device score - never crash, never show a raw stack trace.
Prompt Versioning: Track system-prompt revisions in git (e.g., prompts/summarizer_v2.1.txt), evaluable and roll-back-able.
Latency & Cost Telemetry: Track token usage and end-to-end response times in Firebase Analytics / Datadog / Sentry.

These practices help you understand how your AI features perform in the real world.

Production Checklist & Architecture Recommendations

Run through every box before shipping to the App Store / Play Store.

These include:

API Security
Key Restrictions
Backend Validation
Prompt Injection Defense
Rate Limiting

… and many more

Key Takeaways & Series Summary

As we close out this series, here are the biggest lessons:

AI Engineering is about much more than writing good prompts
Reliability, privacy, and security are first-class concerns
Good architecture makes AI features maintainable
Start simple, but design with production in mind

If you've followed this series from the beginning, you now have a solid foundation for building thoughtful AI features in Flutter.

You can download the AI Engineering Starter Pack with checklists, patterns, and guidance: techwithsam.dev/production-ai-engineering-in-flutter

This brings the AI Engineering for Flutter Developers series to a close.

Thank you for following along.

If this series helped you, I'd really appreciate a like and a comment.

Thanks for reading, and I'll see you in the next one.

Take care!

[Boost]

Samuel Adekunle — Fri, 28 Aug 2026 11:33:18 +0000

Samuel Adekunle

May 8

Clean Architecture in Flutter 2026 - Practical Implementation Guide

#flutter #cleancode #mobile #techwithsam

6 min read

[Boost]

Samuel Adekunle — Thu, 27 Aug 2026 16:33:40 +0000

Samuel Adekunle

Aug 27

AI Engineering for Flutter Developers - AI Agents & Workflows in Flutter

#ai #flutter #agents #techwithsamw

7 min read

AI Engineering for Flutter Developers - AI Agents & Workflows in Flutter

Samuel Adekunle — Thu, 27 Aug 2026 16:32:48 +0000

In the first two articles, we covered the fundamentals and how to build more reliable AI features using structured output, streaming, and proper error handling.

But there's a big limitation with single AI calls: they struggle with complex, multi-step tasks.

That's where AI Agents come in.

Today, we're going to build a simple but powerful multi-agent system in Flutter — specifically, a Planning Agent, a Generation Agent, and a Validation Agent.

By the end of this video, you'll understand how to design agentic workflows and implement them in real Flutter applications.

What Are AI Agents?

An AI Agent is more like giving someone a goal and letting them think, plan, and take multiple steps to achieve it, WHILE a regular LLM call is like asking a smart person one question and getting one answer.

We'll focus on a simple and practical multi-agent pattern:

Planning Agent → Breaks the user request into clear steps
Generation Agent → Executes the plan and creates the output
Validation Agent → Reviews the result and checks for quality

This pattern is extremely useful for real applications.

Designing the Workflow

We'll build a simple Smart Feature Builder,

The user gives a high level request like: 'Create a clean Flutter logins creen with email and password validation.'

Then the system works like this:

The Planning Agent creates a structured plan
The Generation Agent turns that plan into actual code or a UI description
The Validation Agent reviews the output and suggests improvements

Building the Planning Agent

The goal of this agent is to take a vague user request and turn it into a clear, structured plan.

- we define the role and system prompt for the Planning Agent
- we use structured output so we can get a clean list of steps
- then we create a Dart model for the plan
- finally, call the agent and display the result.

import 'dart:convert';
import 'package:googleai_dart/googleai_dart.dart';
import '../models/feature_plan.dart';

/// Stage 1: Planning Agent
/// Takes raw user feature requests and converts them into a structured architectural plan via Gemini API.
class PlanningAgent {
  final String apiKey;
  final String modelName;

  PlanningAgent({
    required this.apiKey,
    this.modelName = 'gemini-3.1-flash-lite',
  });

  static const String _systemInstruction = '''
You are a Senior Flutter Software Architect.
Your role is to take a high-level mobile/web feature request and generate a clean, structured architectural plan.

You must respond ONLY with a valid JSON object matching this exact schema:
{
  "title": "String - Concise title of the feature plan",
  "overview": "String - Executive summary of the architectural strategy",
  "targetPlatform": "String - Target platforms (e.g. Flutter Web, iOS & Android)",
  "componentsToBuild": ["List of String - Individual UI components, widgets, or services to build"],
  "implementationSteps": ["List of String - Sequential step-by-step engineering tasks"],
  "riskConsiderations": ["List of String - Potential state management, security, performance or edge case risks"]
}
''';

  Future<FeaturePlan> planFeature(String prompt) async {
    if (apiKey.isEmpty) {
      throw StateError('Gemini API Key is missing. Please configure your API key before running the pipeline.');
    }

    final config = GoogleAIConfig(authProvider: ApiKeyProvider(apiKey));
    final client = GoogleAIClient(config: config);

    final request = GenerateContentRequest(
      contents: [Content.text('Feature Request:\n$prompt')],
      systemInstruction: Content.text(_systemInstruction),
      generationConfig: const GenerationConfig(
        responseMimeType: 'application/json',
        temperature: 0.2,
      ),
    );

    final response = await client.models.generateContent(
      model: modelName,
      request: request,
    );

    final text = response.text;
    if (text == null || text.trim().isEmpty) {
      throw Exception('Planning Agent returned empty response from Gemini API.');
    }

    final jsonMap = jsonDecode(text) as Map<String, dynamic>;
    return FeaturePlan.fromJson(jsonMap);
  }
}

Building the Generation Agent

This agent takes the structured plan and actually produces the output, in our case, Flutter-related code/content suggestions.

- first, we create the Generation Agent with a clear role
- then pass the plan from the previous agent
- generate the final output
- show how we keep the response structured and useful

import 'dart:convert';
import 'package:googleai_dart/googleai_dart.dart';
import '../models/feature_plan.dart';
import '../models/generated_feature_code.dart';

/// Stage 2: Generation Agent
/// Takes the architectural FeaturePlan and user request, then generates complete, production-ready Flutter code via Gemini API.
class GenerationAgent {
  final String apiKey;
  final String modelName;

  GenerationAgent({
    required this.apiKey,
    this.modelName = 'gemini-3.1-flash-lite',
  });

  static const String _systemInstruction = '''
You are an expert Lead Flutter Engineer.
Your task is to take an Architectural Feature Plan and write production-ready, clean, well-formatted Flutter Dart code.

You must respond ONLY with a valid JSON object matching this exact schema:
{
  "title": "String - Title of the generated feature code",
  "explanation": "String - Clear explanation of key implementation patterns and Dart features used",
  "flutterCode": "String - Complete, fully functioning, syntactically correct Flutter Widget Dart code",
  "dependencies": ["List of String - Required packages in pubspec.yaml (e.g. google_fonts, flutter_animate)"]
}
''';

  Future<GeneratedFeatureCode> generateCode({
    required String userPrompt,
    required FeaturePlan plan,
  }) async {
    if (apiKey.isEmpty) {
      throw StateError('Gemini API Key is missing. Please configure your API key before running the pipeline.');
    }

    final config = GoogleAIConfig(authProvider: ApiKeyProvider(apiKey));
    final client = GoogleAIClient(config: config);

    final promptInput = '''
User Feature Request:
$userPrompt

Architectural Plan:
${plan.toFormattedJson()}
''';

    final request = GenerateContentRequest(
      contents: [Content.text(promptInput)],
      systemInstruction: Content.text(_systemInstruction),
      generationConfig: const GenerationConfig(
        responseMimeType: 'application/json',
        temperature: 0.3,
      ),
    );

    final response = await client.models.generateContent(
      model: modelName,
      request: request,
    );

    final text = response.text;
    if (text == null || text.trim().isEmpty) {
      throw Exception('Generation Agent returned empty response from Gemini API.');
    }

    final jsonMap = jsonDecode(text) as Map<String, dynamic>;
    return GeneratedFeatureCode.fromJson(jsonMap);
  }
}

Building the Validation Agent

This agent acts like a reviewer. It checks the output from the Generation Agent for issues, missing pieces, or areas for improvement.

- again, we create the Validation Agent
- feed it the original request + the generated output
- get structured feedback
- optionally show a simple improvement loop

import 'dart:convert';
import 'package:googleai_dart/googleai_dart.dart';
import '../models/feature_plan.dart';
import '../models/generated_feature_code.dart';
import '../models/validation_report.dart';

/// Stage 3: Validation Agent
/// Reviews generated code against the original user prompt and architectural plan via Gemini API.
class ValidationAgent {
  final String apiKey;
  final String modelName;

  ValidationAgent({
    required this.apiKey,
    this.modelName = 'gemini-3.1-flash-lite',
  });

  static const String _systemInstruction = '''
You are a Lead Code Auditor and Security Reviewer for Flutter applications.
Your job is to audit generated Flutter code against the user request and architectural plan.

You must evaluate code quality, completeness, error handling, accessibility, and performance.
You must respond ONLY with a valid JSON object matching this exact schema:
{
  "qualityScore": 92, // Integer between 0 and 100
  "isPassed": true, // Boolean - true if qualityScore >= 75
  "identifiedIssues": ["List of String - Specific flaws, missing validations, or anti-patterns"],
  "improvementSuggestions": ["List of String - Actionable code quality or performance recommendations"],
  "refinedCodeSnippet": "String or Null - Improved/corrected snippet fixing identified issues"
}
''';

  Future<ValidationReport> validateOutput({
    required String userPrompt,
    required FeaturePlan plan,
    required GeneratedFeatureCode generatedCode,
  }) async {
    if (apiKey.isEmpty) {
      throw StateError('Gemini API Key is missing. Please configure your API key before running the pipeline.');
    }

    final config = GoogleAIConfig(authProvider: ApiKeyProvider(apiKey));
    final client = GoogleAIClient(config: config);

    final promptInput = '''
Original Request:
$userPrompt

Architectural Plan:
${plan.toFormattedJson()}

Generated Code to Audit:
${generatedCode.toFormattedJson()}
''';

    final request = GenerateContentRequest(
      contents: [Content.text(promptInput)],
      systemInstruction: Content.text(_systemInstruction),
      generationConfig: const GenerationConfig(
        responseMimeType: 'application/json',
        temperature: 0.1,
      ),
    );

    final response = await client.models.generateContent(
      model: modelName,
      request: request,
    );

    final text = response.text;
    if (text == null || text.trim().isEmpty) {
      throw Exception('Validation Agent returned empty response from Gemini API.');
    }

    final jsonMap = jsonDecode(text) as Map<String, dynamic>;
    return ValidationReport.fromJson(jsonMap);
  }
}

Putting It All Together

We need to connect everything into one workflow.

We will create a simple orchestrator that:
1. Calls the Planning Agent
2. Passes the plan to the Generation Agent
3. Sends the result to the Validation Agent
4. Displays the final output and feedback

/// Orchestrator Service
/// Coordinates the multi-agent pipeline: Planning -> Generation -> Validation
class AgentOrchestrationService extends ValueNotifier<AgentWorkflowState> {

  ...

  Future<void> runWorkflow(String prompt, {required String apiKey}) async {
    if (prompt.trim().isEmpty) return;

    _addLog('Orchestrator', 'Workflow started for prompt: "$prompt"');

    try {
      // -----------------------------------------------------------------------
      // STAGE 1: Planning Agent
      // -----------------------------------------------------------------------
      _addLog('Planning Agent', 'Analyzing request & composing architectural plan...');
      final planningAgent = PlanningAgent(apiKey: apiKey);
      final plan = await planningAgent.planFeature(prompt);

      value = value.copyWith(
        stage: AgentStage.generating,
        plan: plan,
      );
      _addLog('Planning Agent', 'Plan generated successfully: "${plan.title}"', payload: plan.toFormattedJson());

      // -----------------------------------------------------------------------
      // STAGE 2: Generation Agent
      // -----------------------------------------------------------------------
      _addLog('Generation Agent', 'Writing Flutter code & module dependencies...');
      final generationAgent = GenerationAgent(apiKey: apiKey);
      final generatedCode = await generationAgent.generateCode(
        userPrompt: prompt,
        plan: plan,
      );

      value = value.copyWith(
        stage: AgentStage.validating,
        generatedCode: generatedCode,
      );
      _addLog('Generation Agent', 'Code generated successfully (${generatedCode.flutterCode.length} chars)', payload: generatedCode.toFormattedJson());

      // -----------------------------------------------------------------------
      // STAGE 3: Validation Agent
      // -----------------------------------------------------------------------
      _addLog('Validation Agent', 'Auditing code quality, security & accessibility...');
      final validationAgent = ValidationAgent(apiKey: apiKey);
      final validationReport = await validationAgent.validateOutput(
        userPrompt: prompt,
        plan: plan,
        generatedCode: generatedCode,
      );

      _tickerTimer?.cancel();

      value = value.copyWith(
        stage: AgentStage.completed,
        validationReport: validationReport,
      );
      _addLog('Validation Agent', 'Audit complete. Quality Score: ${validationReport.qualityScore}/100 (Passed: ${validationReport.isPassed})', payload: validationReport.toFormattedJson());
      _addLog('Orchestrator', 'Multi-Agent pipeline executed successfully!');
    } catch (e) {
      _tickerTimer?.cancel();
      _addLog('Orchestrator', 'Pipeline failed: $e');
      value = value.copyWith(
        stage: AgentStage.failed,
        error: e,
      );
    }
  }
}

The full source code is on GitHub: github.com/techwithsam/ai_engineer_for_flutter_devs/tree/video-3

Recap & Key Takeaways

Quick summary of what we covered:

AI Agents allow us to handle multi-step tasks much better than single prompts
The Planning → Generation → Validation pattern is simple but powerful
Structured output is critical when agents need to communicate
Keeping the architecture clean makes these systems maintainable

This is a foundational pattern you can expand in many directions.

If you haven't already, download the free AI Engineering Starter Pack - I've updated it with the code and patterns from this article.

Here: techwithsam.dev/ai-starter-kit-3

Just enter your email, and it will be sent to you instantly.

In the next and final video of this series, we'll focus on Production AI Engineering - covering performance, privacy, security, evaluation, and best practices for shipping AI features in real Flutter apps.

If you found this valuable, please like and drop a comment.

I'd love to know: What kind of multi-agent workflow would you like to see next?

Thank you for following. I'll see you in the final one.

Take care!

AI Engineering for Flutter Developers — Building Reliable AI Features in Flutter

Samuel Adekunle — Wed, 19 Aug 2026 16:13:10 +0000

Building a reliable AI feature that works well in production is not so easy; it's a completely different skill.

For this part 2, we're going to focus on three critical skills every AI Engineer needs, i.e

Mastering Structured AI Outputs
Real-Time Streaming
Building a Robust Error Handling System

By the end, we will know how to build AI features that are cleaner, more predictable, and much more enterprise-ready.

What You'll Learn in This Part:

Why free-text AI responses are dangerous to production Flutter Apps
How to force structured, typed responses using Gemini
How to implement streaming for better user experience in Flutter
How to handle AI failures gracefully in Flutter

Structured Output

Let's start with Structured Output.

When you ask an AI model a question, by default, it returns free text (plain text), which is flexible but dangerous and hard to work with in real applications.

Structured Output allows the model to return clean, predictable data, usually in JSON format, just like when we are integrating an endpoint.

Here is an example of how to do this properly with Gemini in Flutter.

Future<ArticleBlueprint> generateStructuredBlueprint(
    String topicPrompt, {
    void Function(int attempt, Duration delay, Exception error)? onRetry,
  }) async {

    return RetryHelper.retryWithBackoff<ArticleBlueprint>(
      onRetry: onRetry,
      maxAttempts: 3,
      action: () async {
        GoogleAIClient? client;
        try {
          // 1. Initialize client using googleai_dart
          client = GoogleAIClient(
            config: GoogleAIConfig(
              authProvider: ApiKeyProvider(apiKey),
            ),
          );

          // 2. Build Structured JSON prompt enforcing strict schema
          final systemPrompt = '''
You are a technical content architect. Generate a structured JSON blueprint for a technical article or feature guide.

STRICT JSON SCHEMA REQUIREMENT:
Return ONLY a valid JSON object with the following fields:
- "title": String (compelling article title)
- "overview": String (concise 2-3 sentence overview)
- "difficulty": String ("Beginner", "Intermediate", or "Advanced")
- "estimatedReadingMinutes": Integer
- "tags": Array of Strings
- "keyConcepts": Array of Strings (up to 4 bullet points)
- "implementationSteps": Array of Strings (step-by-step implementation guide)
- "codeSnippet": String (short code example)

Topic to generate blueprint for:
"$topicPrompt"
''';

          // 3. Make API request using client.models.generateContent
          final response = await client.models.generateContent(
            model: modelName,
            request: GenerateContentRequest(
              contents: [
                Content(
                  parts: [TextPart(systemPrompt)],
                  role: 'user',
                ),
              ],
            ),
          );

          // 4. Extract generated text payload
          final candidate = response.candidates?.firstOrNull;
          if (candidate?.finishReason == FinishReason.safety ||
              candidate?.finishReason?.name.toLowerCase() == 'safety') {
            throw const SafetyRefusalAIException(
              'The requested topic was flagged by Gemini safety filters.',
            );
          }

          final parts = candidate?.content?.parts ?? [];
          final rawText = parts
              .whereType<TextPart>()
              .map((p) => p.text)
              .join('\n');

          if (rawText.isEmpty) {
            throw const SchemaParsingAIException(
              'Received empty output from Gemini model.',
              rawOutput: '',
            );
          }

          // 5. Clean markdown code blocks & parse JSON
          final cleanJsonText = _cleanMarkdownJson(rawText);
          final jsonMap = jsonDecode(cleanJsonText) as Map<String, dynamic>;

          // 6. Deserialize into strongly-typed Dart model
          return ArticleBlueprint.fromJson(jsonMap, rawText);
        } catch (e) {
          throw _translateException(e);
        } finally {
          client?.close();
        }
      },
    );
  }

This alone will make the AI feature more reliable.

Streaming Responses

Next up is Real-Time Streaming

Nobody likes staring at a loading spinner while waiting for a long AI response. With streaming, we can let the text appear gradually, just like a typewriter, which feels much more natural and responsive.

Let's implement streaming with Gemini in Flutter

/// Token Streaming (`streamGenerateContent`).
  ///
  /// Yields incremental text tokens as they arrive from Gemini in real-time.
  Stream<String> streamTextContent(String prompt) async* {
    GoogleAIClient? client;
    try {
      client = GoogleAIClient(
        config: GoogleAIConfig(
          authProvider: ApiKeyProvider(apiKey),
        ),
      );

      final stream = client.models.streamGenerateContent(
        model: modelName,
        request: GenerateContentRequest(
          contents: [
            Content(
              parts: [TextPart(prompt)],
              role: 'user',
            ),
          ],
        ),
      );

      await for (final response in stream) {
        final candidate = response.candidates?.firstOrNull;
        final parts = candidate?.content?.parts ?? [];
        final token = parts
            .whereType<TextPart>()
            .map((p) => p.text)
            .join();

        if (token.isNotEmpty) {
          yield token;
        }
      }
    } catch (e) {
      throw _translateException(e);
    } finally {
      client?.close();
    }
  }

As simple as that…

Error Handling & Resilience

This is the part most devs skip, and it's one of the reasons many AI features break in production.

AI calls can fail for many reasons:

Network issues
Rate limits
Invalid responses
Timeouts
Model refusing the request

Let's create a simulation of a proper error handling system that includes:

Clear error types
Retry logic
Meaningful feedback to the user
Fallback behaviour

/// DEMO HELPER: Simulates intentional fault cases.
  Future<ArticleBlueprint> simulateFault(String faultType) async {
    await Future.delayed(const Duration(milliseconds: 600));

    switch (faultType) {
      case '429_rate_limit':
        throw const RateLimitAIException(
          'HTTP 429: Too Many Requests. Gemini rate limit reached.',
          retryAfter: Duration(seconds: 5),
        );
      case 'network_timeout':
        throw const NetworkAIException(
          'SocketException: Connection timed out while reaching api.generativeai.google',
        );
      case 'schema_invalid':
        throw const SchemaParsingAIException(
          'FormatException: Missing mandatory "title" key in JSON payload.',
          rawOutput: '{"overview": "Broken JSON example without title"}',
        );
      case 'safety_refusal':
        throw const SafetyRefusalAIException(
          'Prompt blocked by Gemini Safety Classifier Policy.',
        );
      default:
        throw const UnknownAIException('Simulated unknown exception.');
    }
  }

Now we can combine everything we've learned into a more complete example.

Source code on GitHub

techwithsam / ai_engineer_for_flutter_devs

AI Engineering for Flutter Devs 2026 - TechWithSam

AI Engineering for Flutter Developers – Smart Text Analyzer

Free resource from Tech With Sam — companion repo for the AI Engineering for Flutter Developers YouTube series.

📦 What's in This Repo

Folder / File	Contents
`/lib/services`	Cloud Gemini (`GeminiService`), On-Device TFLite (`OnDeviceClassifierService`), & Resilient AI Engine (`ResilientAIService`, `RetryHelper`)
`/lib/models`	Data models (`TextAnalysisResult`), Structured Output schemas (`ArticleBlueprint`), & Custom AI Exceptions (`ai_exceptions.dart`)
`/lib/widgets`	UI components: Gemini/On-Device cards, `StreamingOutputWidget`, `StructuredBlueprintCard`, & `ErrorResilienceBanner`
`/lib/theme`	Dark & light mode brand theme system (`AppTheme`)
`/lib/part_two_app.dart`	Video 2 entry point & studio screen for Structured Output, Token Streaming, and Fault Injection testing
`/lib/main.dart`	Main root app launcher coexisting across all video series modules

🚀 Quick Setup

# 1. Clone the repo
git clone https://github.com/techwithsam/ai_engineer_for_flutter_devs.git
# 2. Navigate into the project
cd ai_engineer_for_flutter_devs

# 3. Get dependencies
flutter

…

View on GitHub

Recap & Key Takeaways

Today we covered:

Always prefer Structured Output when you need predictable data
Use streaming to improve perceived performance
Treat error handling as a priority and first-class citizen

These three practices will immediately raise the quality of any AI feature you build in Flutter.

If you haven't already, download the free AI Engineering Starter Pack — I've updated it with the code and patterns from this article.

Here: techwithsam.dev/ai-starter-kit-2

Just enter your email, and it will be sent to you instantly.

If you found this valuable, please hit the like clap, follow, and turn on notifications so you don't miss the rest of this series.

In the next release, we'll go into AI Agents and Workflows

Drop a comment and tell me: What's one AI feature you want to build in your Flutter app?

Thank you for following. I'll see you in the next one.

Take care!

AI Engineering for Flutter Developers – Getting Started with Gemini & On-Device AI

Samuel Adekunle — Thu, 13 Aug 2026 15:13:31 +0000

It's been a while since my last release. You know, life happened :(

I'm back now with more positive energy, and I'm starting a brand new series titled AI Engineering for Flutter Developers.

This series is about helping you become a better AI Engineer as a Flutter developer, someone who can thoughtfully integrate AI into production-grade mobile apps, understand the concepts, make smart architecture decisions, and ship reliable features.

We're starting from the fundamentals, i.e mindset shift, key concepts you need to know, and building your very first practical AI feature using Gemini and on-device models.

If you've been overwhelmed by all the AI noise on socials (esp. X), this series is for you.

It's no longer a secret that most (if not all) developers right now are AI users, i.e they use AI to perform coding tasks (copy prompts, paste code) and hope it works.

As Flutter developers, we need to become AI Engineers.

What does that mean?

You understand when to use on-device vs cloud AI
You know how to evaluate quality and handle failures
You design proper architecture around AI features
You care about privacy, performance, cost, and user experience

Key AI Concepts Every Developer Should Know

LLMs (Large Language Models): Gemini, Claude, etc.
Embeddings: Turning text/images into numbers for comparison
RAG (Retrieval Augmented Generation): Giving AI your own data
Tool Calling / Function Calling: Letting AI trigger actions
Agents: AI that can plan and execute multi-step tasks
On-device AI: Running models locally for privacy and speed

We'll use all of these throughout the series, so keep them in mind.

Practical Setup (Gemini + On-Device)

First, let's get set up.

Get your Gemini API key from Google AI Studio

Add the necessary packages:

dependencies:
  googleai_dart: ^latest
  tflite_flutter: ^latest

Basic Gemini call example:

import 'package:googleai_dart/googleai_dart.dart';

Future<void> main() async {
  final client = GoogleAIClient.fromEnvironment();

  try {
    final response = await client.models.generateContent(
      model: 'gemini-3.5-flash',
      request: GenerateContentRequest(
        contents: [Content.text('Explain why Dart works well for APIs.')],
      ),
    );

    print(response.text);
  } finally {
    client.close();
  }
}

Simple on-device model setup (we'll use a lightweight classification model):

/// Initialize TFLite Interpreter if asset model is provided.
  Future<void> initializeModel({String? modelPath}) async {
    if (modelPath != null) {
      try {
        _interpreter = await Interpreter.fromAsset(modelPath);
        _isInitialized = true;
      } catch (e) {
        debugPrint('TFLite native model initialization note: $e');
        _isInitialized = false;
      }
    }
  }

Now let's build something useful together.

We're going to create a Smart Text Analyzer feature that can:

Use Gemini to summarize or extract insights
Use an on-device model for quick classification (e.g., sentiment or category)
Show both results side by side

Creating a structured prompt for JSON output with Gemini

/// Analyzes input text using Google Gemini AI via googleai_dart client.
  Future<GeminiInsight> analyzeText(String inputText) async {
    if (apiKey.trim().isEmpty) {
      throw Exception(
        'Gemini API Key is missing. Tap the key icon in the app bar to configure your key.',
      );
    }

    if (inputText.trim().isEmpty) {
      throw Exception('Input text cannot be empty.');
    }

    GoogleAIClient? client;
    try {
      // 1. Instantiate client using GoogleAIConfig and ApiKeyProvider from googleai_dart
      client = GoogleAIClient(
        config: GoogleAIConfig(
          authProvider: ApiKeyProvider(apiKey),
        ),
      );

      // 2. Format structured prompt for JSON output
      final prompt = '''
Analyze the following text and extract structured insights. Return ONLY a valid JSON object with:
- "summary": A concise 2-3 sentence summary of the key message.
- "keyInsights": A list of up to 4 main takeaways.
- "actionItems": A list of relevant action items or follow-ups suggested by the text (or empty list [] if none).
- "tone": The overall tone (e.g., Professional, Urgent, Enthusiastic, Frustrated, Informative).

Text to analyze:
"$inputText"
''';

      // 3. Send request to Gemini API via client.models.generateContent
      final response = await client.models.generateContent(
        model: modelName,
        request: GenerateContentRequest(
          contents: [
            Content(
              parts: [TextPart(prompt)],
              role: 'user',
            ),
          ],
        ),
      );

      // 4. Extract generated text from response candidate
      final candidate = response.candidates?.firstOrNull;
      final parts = candidate?.content?.parts ?? [];
      final rawText = parts
          .whereType<TextPart>()
          .map((p) => p.text)
          .join('\n');

      if (rawText.isEmpty) {
        throw Exception('Received an empty response from Gemini API.');
      }

      return _parseResponse(rawText);
    } catch (e) {
      if (e is Exception) rethrow;
      throw Exception('Gemini API Error: $e');
    } finally {
      client?.close();
    }
  }

On-device classification

/// Classifies text locally on device and measures inference latency.
  Future<OnDeviceClassification> classifyText(String text) async {
    // ....... 

    // Fast high-speed local token analysis engine (on-device fallback)
    final words = _tokenize(text);
    final detectedKeywords = <String>{};

    double posScore = 0.0;
    double negScore = 0.0;

    for (final word in words) {
      if (_positiveWords.containsKey(word)) {
        posScore += _positiveWords[word]!;
        detectedKeywords.add(word);
      }
      if (_negativeWords.containsKey(word)) {
        negScore += _negativeWords[word]!;
        detectedKeywords.add(word);
      }
    }

    // Sentiment Determination
    String sentiment = 'Neutral';
    double sentimentConfidence = 0.5;

    if (posScore > negScore && posScore > 0.3) {
      sentiment = 'Positive';
      sentimentConfidence = min(0.99, 0.55 + (posScore / (posScore + negScore + 1.0)) * 0.44);
    } else if (negScore > posScore && negScore > 0.3) {
      sentiment = 'Negative';
      sentimentConfidence = min(0.99, 0.55 + (negScore / (posScore + negScore + 1.0)) * 0.44);
    } else {
      sentiment = 'Neutral';
      sentimentConfidence = 0.65;
    }

    // Category Determination
    final categoryScores = <String, double>{};
    for (final entry in _categoryKeywords.entries) {
      double score = 0.0;
      for (final kw in entry.value) {
        if (words.contains(kw)) {
          score += 1.0;
          detectedKeywords.add(kw);
        }
      }
      categoryScores[entry.key] = score;
    }

    // .......
  }

Full source code here:

techwithsam / ai_engineer_for_flutter_devs

AI Engineering for Flutter Devs 2026 - TechWithSam

AI Engineering for Flutter Developers – Smart Text Analyzer

Free resource from Tech With Sam — companion repo for the AI Engineering for Flutter Developers YouTube series.

📦 What's in This Repo

Folder / File	Contents
`/lib/services`	Cloud Gemini (`GeminiService`), On-Device TFLite (`OnDeviceClassifierService`), & Resilient AI Engine (`ResilientAIService`, `RetryHelper`)
`/lib/models`	Data models (`TextAnalysisResult`), Structured Output schemas (`ArticleBlueprint`), & Custom AI Exceptions (`ai_exceptions.dart`)
`/lib/widgets`	UI components: Gemini/On-Device cards, `StreamingOutputWidget`, `StructuredBlueprintCard`, & `ErrorResilienceBanner`
`/lib/theme`	Dark & light mode brand theme system (`AppTheme`)
`/lib/part_two_app.dart`	Video 2 entry point & studio screen for Structured Output, Token Streaming, and Fault Injection testing
`/lib/main.dart`	Main root app launcher coexisting across all video series modules

🚀 Quick Setup

# 1. Clone the repo
git clone https://github.com/techwithsam/ai_engineer_for_flutter_devs.git
# 2. Navigate into the project
cd ai_engineer_for_flutter_devs

# 3. Get dependencies
flutter

…

View on GitHub

Recap & Key Takeaways

Today we covered:

The difference between an AI user and an AI Engineer
Core concepts you need
How to set up Gemini and basic on-device AI
Your first working AI feature in Flutter

This is just the foundation. The real power comes in the next article.

Before you go - I've prepared a free AI Engineering Starter Pack for you.
It includes:

Setup guides
Reusable components
Prompt templates
And a few exclusive extras

You can download it for free at: techwithsam.dev/ai-starter-kit

Just enter your email, and it will be sent to you instantly.

If you found this valuable, please hit the like clap, follow, and turn on notifications so you don't miss the rest of this series.

This is Part 1 of the AI Engineering for Flutter Devs series.

In the next release, we'll go deeper into building reliable, production-ready AI features.

Drop a comment and tell me: What's one AI feature you want to build in your Flutter app?

Thank you for following. Welcome back to the journey with me, and I'll see you in the next one.

Take care!

Clean Architecture in Flutter 2026 - Practical Implementation Guide

Samuel Adekunle — Fri, 08 May 2026 11:55:52 +0000

Disclaimer! I know you can easily generate MVVM structure with AI, but understanding the fundamentals and how it works is what differentiates a software engineer from a vibe coder, and teaching the fundamentals is what this article is all about…

If your project folder is starting to feel like spaghetti and you’re scared to touch any file because everything is connected to everything… this article is for you.

In 2026, Clean Architecture is no longer “nice to have.” It’s how professional Flutter teams ship maintainable, testable, and scalable apps.

Today, I’m showing you a practical and tested approach that aligns with Flutter’s own official architecture recommendations: MVVM with a Feature-First folder structure. This is what the Flutter team themselves recommend, and I’ll show you how to actually use it in production.

By the end, you’ll have a clear folder structure, dependency rules, and a real working example you can start using today. Let’s clean this up.

WHY CLEAN ARCHITECTURE STILL MATTERS IN 2026

Flutter has grown massively, but the problems haven’t changed:

Features keep getting added
Teams grow
Requirements change constantly

The Flutter team’s own architecture guide says it best: Separation of Concerns is the most important principle to follow when designing your Flutter app.

When you apply it properly:

UI changes don’t break business logic
You can swap Firebase for Supabase with minimal pain
Testing becomes actually enjoyable
New developers can be onboarded in days instead of weeks

The key in 2026 is combining MVVM (the pattern Flutter officially recommends) with Feature-First folder organisation — grouping files by feature, not by type.

Flutter’s guide breaks every feature down into four key components: Views, View Models, Repositories, and Services. That’s exactly what we’re building today.

THE RECOMMENDED FOLDER STRUCTURE

Here’s the practical structure I recommend, and it’s built around Flutter’s official MVVM guidance:

lib/
├── core/                    # Never depends on features
│   ├── di/                  # Dependency Injection (Riverpod)
│   ├── network/
│   ├── utils/
│   ├── theme/
│   └── constants.dart
│
├── features/
│   ├── auth/
│   ├── notes/               # ← Example feature (we'll build this)
│   ├── tasks/
│   └── profile/
│
└── shared/                  # Shared widgets, models if needed

Inside each feature (e.g. notes/), we follow Flutter's own MVVM layers:

notes/
├── presentation/            # UI layer (Flutter's recommended term)
│   ├── screens/             # Views — widget compositions
│   ├── widgets/
│   └── view_models/         # ViewModels — logic + UI state
│
├── domain/                  # Optional: Domain layer for complex use-cases
│   ├── entities/
│   ├── repositories/        # Abstract contracts (interfaces)
│   └── use_cases/           # Interactors — only add when needed
│
└── data/                    # Data layer
    ├── models/              # DTOs — raw API/DB response shapes
    ├── services/            # One class per data source (REST, local, platform)
    └── repositories/        # Implementations of abstract contracts

Notice: Flutter’s official guide uses the term Services for what many tutorials call datasources. Services wrap individual API endpoints into a single class per data source. Repositories sit above them and handle business logic such as caching, error handling, and retries.

MVVM + DEPENDENCY RULES (The Flutter-Official Way)

Flutter’s architecture guide recommends MVVM (Model-View-ViewModel). Here’s how it maps:

The golden rule: dependencies only point inward (toward data).

View → ViewModel → Repository → Service

Views contain only display logic: if-statements to show/hide widgets, animation logic, and layout based on screen size. No business logic in widgets.
ViewModels contain all the logic: filtering, sorting, transforming data, managing UI state, and exposing commands that views call on button presses.
Repositories are the single source of truth for your app’s data. They handle caching, error handling, retry logic, and polling. One repository per data type.
Services are the lowest layer; they wrap external endpoints (REST APIs, local files, platform APIs) and expose Future or Stream objects. They hold no state.

Views and ViewModels have a one-to-one relationship.

Repositories and ViewModels have a many-to-many relationship — one ViewModel can use several repositories, and one repository can serve many ViewModels.

This is Dependency Inversion in action, and it’s what Flutter officially recommends.

PRACTICAL EXAMPLE — Building a Notes Feature

Let’s implement this together, top to bottom.

Services Layer (lowest — wraps data sources)

// data/services/notes_remote_service.dart
class NotesRemoteService {
  final http.Client _client;

  Future<List<Map<String, dynamic>>> fetchNotes() async {
    final response = await _client.get(Uri.parse('/api/notes'));
    return jsonDecode(response.body) as List<Map<String, dynamic>>;
  }
}

// data/services/notes_local_service.dart
class NotesLocalService {
  // Wraps local storage - SharedPreferences, SQLite, Hive etc.
  Future<List<Map<String, dynamic>>> getCachedNotes() async { ... }
  Future<void> cacheNotes(List<Map<String, dynamic>> notes) async { ... }
}

Services are thin. They do one job: talk to the data source and return raw data.

2. Repository Layer (source of truth — handles business logic)

// domain/repositories/notes_repository.dart
abstract class NotesRepository {
  Stream<List<Note>> watchNotes();
  Future<void> saveNote(Note note);
  Future<void> deleteNote(String id);
}

// data/repositories/notes_repository_impl.dart
class NotesRepositoryImpl implements NotesRepository {
  final NotesRemoteService _remote;
  final NotesLocalService _local;

  @override
  Stream<List<Note>> watchNotes() async* {
    // Serve from cache first, then fetch fresh data
    final cached = await _local.getCachedNotes();
    yield cached.map(Note.fromMap).toList();

    final fresh = await _remote.fetchNotes();
    await _local.cacheNotes(fresh);
    yield fresh.map(Note.fromMap).toList();
  }
}

The repository handles caching logic, error handling, and data transformation. The ViewModel never talks directly to services.

3. Domain Layer — Use-Cases (optional — add when needed)

Flutter’s guide recommends adding use cases only when:

You need to merge data from multiple repositories
The logic is exceedingly complex
The logic will be reused across multiple ViewModels

Don’t add use-cases by default — that’s over-engineering. Add them when you spot repetition.

// domain/use_cases/get_sorted_notes.dart
class GetSortedNotesUseCase {
  final NotesRepository _notes;
  final UserRepository _user; // merges data from two repositories

  Stream<List<Note>> call() {
    return _notes.watchNotes().map((notes) =>
      notes..sort((a, b) => b.createdAt.compareTo(a.createdAt))
    );
  }
}

4. ViewModel Layer (UI logic + state)

// presentation/view_models/notes_view_model.dart
@riverpod
class NotesViewModel extends _$NotesViewModel {
  @override
  Future<List<Note>> build() async {
    // Watch the repository - reactive updates automatically
    return ref.watch(notesRepositoryProvider).watchNotes().first;
  }

  // Commands - exposed to the View for button presses etc.
  Future<void> deleteNote(String id) async {
    await ref.read(notesRepositoryProvider).deleteNote(id);
    ref.invalidateSelf();
  }

  Future<void> saveNote(Note note) async {
    await ref.read(notesRepositoryProvider).saveNote(note);
    ref.invalidateSelf();
  }
}

ViewModels expose commands — Dart functions that the view calls in response to user interaction. The view never knows what happens inside. That’s the command pattern in action.

5. View Layer (widgets — display only)

// presentation/screens/notes_screen.dart
class NotesScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final notesAsync = ref.watch(notesViewModelProvider);

    return Scaffold(
      body: notesAsync.when(
        data: (notes) => NotesList(
          notes: notes,
          // Pass commands from ViewModel - view doesn't know implementation
          onDelete: (id) => ref.read(notesViewModelProvider.notifier).deleteNote(id),
        ),
        loading: () => const CircularProgressIndicator(),
        error: (e, _) => Text('Error: $e'),
      ),
    );
  }
}

The view only has display logic, conditional rendering, animations, and layout. All data logic lives in the ViewModel. COMMON MISTAKES TO AVOID

Putting business logic inside widgets,

If your widget is doing data transformation, sorting, or API calls, that belongs in the ViewModel.
Making repositories depend on each other,

Flutter's guide is clear: repositories should never be aware of each other. If you need data from two repositories, combine them in the ViewModel or in a use case.
Adding use-cases everywhere by default,

The domain layer is optional. Flutter's own guide says to add use-cases only when needed - not for every feature. Unnecessary use-cases add boilerplate and cognitive load without benefit.
Skipping Services - going directly from,

Repository to HTTP Services are what make your repositories testable. Without them, you can't mock your data layer properly. One service per data source is the official recommendation.
Ignoring Dependency Injection,

Riverpod 3+ makes this clean and type-safe. Every component, service, and ViewModel should be injected, not instantiated directly.

Want the complete clean architecture starter template with the full Notes feature already implemented — including Riverpod 3+, services, repositories, a ViewModel, tests, and the full folder structure aligned with Flutter’s official guide?

It’s free in my newsletters. Just comment “CLEAN” below or use this link and I’ll send you my weekly newsletter, which will contain the GitHub repo link.

FINAL TIPS & WHEN TO START

Don’t rewrite your entire project. Start applying this to your next new feature.

Refactor one screen at a time, extract your services, then your repository, then lift logic into a ViewModel.

The official Flutter guide puts it well: these are guidelines, not rigid rules. Adapt them to your project’s actual needs. A small solo project might not need a domain layer at all. A large team app probably will.

Clean architecture isn’t about being perfect. It’s about making your future self and your teammates thankful they didn’t have to dig through a 500-line widget to find a bug.

That’s the practical way to implement Flutter architecture: MVVM with Feature-First organisation, aligned with what the Flutter team themselves recommend.

Views display. ViewModels manage state and logic. Repositories are your source of truth. Services talk to the outside world. Domain use-cases come in only when you genuinely need them.

If this article gave you clarity, hit the like button and subscribe for more production-grade Flutter content.

Now go organise that project.

I’ll see you in the next one — peace! ✌️

Samuel Adekunle

Tech With Sam

https://youtube.com/@techwithsam