Flashcards are one of the most effective study tools because they use active recall: you actively try to remember the answer instead of passively reading notes. Research shows this strengthens memory and helps information stick.

In this tutorial, you'll build a full-stack flashcard app that lets students:

• Create subjects (like "Biology 101" or "Calculus")

• Add flashcards with a question on the front and answer on the back

• Study by flipping cards and marking them correct or wrong

• Track progress to see how well they're doing

By the end, you'll have a working app that stores data in MongoDB and runs on Next.js. No prior experience with these tools is required. We'll explain everything as we go.

Table of Contents

• What You'll Learn

• Tech Stack Overview

• Project Setup

  • Step 1: Create the Next.js Project

  • Step 2: Install Mongoose

  • Step 3: Set Up MongoDB

  • Step 4: Create the Environment File

  • Step 5: Understand the Folder Structure

• Building the Features

  • Part 1: Connecting to MongoDB

  • Part 2: Defining the Data Models

    • Subject Model

    • Flashcard Model

    • Progress Model

  • Part 3: Creating Subjects and Flashcards (API Routes)

    • Subjects API – List and Create

    • Flashcards API – List and Create

  • Part 4: Editing and Deleting (Dynamic API Routes)

    • Subject by ID – Get, Update, Delete

    • Flashcard by ID – Get, Update, Delete

  • Part 5: Progress Tracking API

• UI Implementation

  • The Subjects Page

  • The Subject Detail Page (Creating and Editing Flashcards)

  • The Study Page – Flipping Cards

    • The Flip Animation

    • Recording Progress

  • The Progress Page

• Best Practices

  • Code Organization

  • Error Handling

  • Performance Tips

• Conclusion

What You'll Learn

• How to set up a Next.js project with TypeScript

• How to connect to MongoDB and store data

• How to build API routes for creating, reading, updating, and deleting data

• How to build a React UI with forms, lists, and interactive flashcards

• How to add a flip animation and progress tracking

Tech Stack Overview

Before we start coding, here's what we're using and why.

Next.js

Next.js is a React framework for building web applications. It handles routing, server-side rendering, and API routes out of the box.

Instead of building a separate frontend and backend, Next.js lets us put both in one project. We can create API routes (like /api/flashcards) that talk to the database, and pages that display the UI, all in the same codebase.

MongoDB

MongoDB is a NoSQL database that stores data as JSON-like documents. Unlike traditional tables with rows and columns, you store flexible "documents" in "collections."

MongoDB is beginner-friendly, works well with JavaScript/TypeScript, and has a generous free tier (MongoDB Atlas) or can run locally with Docker.

Mongoose

Mongoose is a library that lets you define schemas and models for MongoDB. It adds structure and validation so you don't accidentally save invalid data.

Without Mongoose, you'd write raw MongoDB queries. With Mongoose, you define a "Flashcard" model once and use simple methods like Flashcard.create() or Flashcard.find().

Tailwind CSS

Tailwind is a utility-first CSS framework. Instead of writing custom CSS, you add classes like rounded-xl or bg-blue-500 directly in your HTML.

Tailwind speeds up styling and keeps the design consistent. Next.js supports it out of the box.

Project Setup

Step 1: Create the Next.js Project

Open your terminal and run:

npx create-next-app@latest flash-cards --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm

When prompted, choose:

• TypeScript: Yes

• ESLint: Yes

• Tailwind CSS: Yes

• src/ directory: Yes

• App Router: Yes

• Import alias: @/*

This creates a new folder called flash-cards with a basic Next.js app.

Step 2: Install Mongoose

Mongoose is not included by default. Run the commands below to Install it.

cd flash-cards
npm install mongoose

Step 3: Set Up MongoDB

You have two options:

Option A: Docker (recommended for local development)

Create a file called docker-compose.yml in your project root:

services:
  mongodb:
    image: mongo:7
    container_name: flashstudy-mongodb
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

Then run:

docker compose up -d

This starts MongoDB in the background. Your data is stored in a Docker volume, so it persists even if you stop the container.

Option B: MongoDB Atlas (cloud)

1. Go to mongodb.com/cloud/atlas

2. Create a free account and cluster

3. Create a database user and get your connection string

4. Add your IP to the network access list

Step 4: Create the Environment File

Create a file named .env.local in your project root (this file is ignored by Git for security):

MONGODB_URI=mongodb://localhost:27017/flashcards

If you're using Atlas, replace this with your connection string, for example:

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/flashcards?retryWrites=true&w=majority

Step 5: Understand the Folder Structure

After setup, your project looks like this:

flash-cards/
├── src/
│   ├── app/              # Pages and API routes
│   │   ├── api/          # Backend API endpoints
│   │   ├── subjects/     # Subject list and detail pages
│   │   ├── study/        # Study mode page
│   │   └── progress/     # Progress tracking page
│   ├── components/       # Reusable UI components
│   └── lib/              # Utilities and database code
│       ├── db.ts         # MongoDB connection
│       └── models/       # Mongoose schemas
├── .env.local            # Environment variables (you create this)
├── docker-compose.yml    # Docker config for MongoDB
└── package.json

The app folder uses Next.js App Router: each folder can have a page.tsx (the UI) and route.ts (API endpoints). We'll build these step by step.

Building the Features

Part 1: Connecting to MongoDB

Before we can store or retrieve flashcards, we need to connect our application to MongoDB.

We'll create a small database utility that handles this connection for us. Because Next.js can handle multiple requests and reload modules during development, we don't want to create a new MongoDB connection every time an API route runs. Instead, we'll cache the connection and reuse it whenever possible.

Let's start by creating a db.ts file inside the src/lib directory.

import mongoose from "mongoose";

const MONGODB_URI = process.env.MONGODB_URI || "mongodb://localhost:27017/flashcards";

interface MongooseCache {
  conn: typeof mongoose | null;
  promise: Promise<typeof mongoose> | null;
}

declare global {
  var mongoose: MongooseCache | undefined;
}

let cached: MongooseCache = global.mongoose || { conn: null, promise: null };

if (!global.mongoose) {
  global.mongoose = cached;
}

async function dbConnect(): Promise<typeof mongoose> {
  if (cached.conn) return cached.conn;

  if (!cached.promise) {
    cached.promise = mongoose.connect(MONGODB_URI, {
      bufferCommands: false,
    });
  }

  cached.conn = await cached.promise;
  return cached.conn;
}

export default dbConnect;

Here's a line-by-line explanation of this code:

• MONGODB_URI: Reads the connection string from .env.local. Falls back to local MongoDB if not set.

• MongooseCache: A TypeScript interface describing our cache: we store either a connection (conn) or a promise that will eventually give us one.

• global.mongoose: In development, Next.js may reload modules. Using global keeps our cache across reloads so we don't create duplicate connections.

• dbConnect(): If we already have a connection, return it. Otherwise, create one, cache it, and return it. Every API route will call await dbConnect() before touching the database.

Part 2: Defining the Data Models

Now that our application can connect to MongoDB, let's define the data we'll store in the database.

Our flashcard app needs three types of data:

• Subjects: Categories such as Biology 101 or Calculus.

• Flashcards: Questions and answers that belong to a subject.

• Progress: Records of how well the user performs when studying.

We'll use Mongoose schemas to define the structure of each type of data. A schema describes the fields a document can have and the type of data each field should contain.

Let's start with the Subject model.

Subject Model

A subject represents a category of flashcards. For example, a student might create a subject called Biology 101 and use it to organize their biology flashcards.

Each subject will have a name, an optional description, and a color that we'll use when displaying the subject in the UI.

First, create a models directory inside src/lib if you haven't already. Then create a file named Subject.ts inside it.

import mongoose, { Schema, model, models } from "mongoose";

export interface ISubject {
  _id: string;
  name: string;
  description?: string;
  color: string;
  createdAt: Date;
  updatedAt: Date;
}

const SubjectSchema = new Schema(
  {
    name: { type: String, required: true },
    description: { type: String },
    color: { type: String, default: "#6366f1" },
  },
  { timestamps: true }
);

export default models.Subject || model<ISubject>("Subject", SubjectSchema);

In this code:

• ISubject: TypeScript interface. Describes what a subject object looks like in our app.

• SubjectSchema – Mongoose schema. name is required, while description and color are optional. color defaults to a purple hex.

• timestamps: true: Mongoose automatically adds createdAt and updatedAt to every document.

• models.Subject || model(...): In development, modules can reload. This prevents "model already defined" errors by reusing the existing model if it exists.

Flashcard Model

A flashcard belongs to a subject and contains a question on the front and an answer on the back.

Next, let's create the Flashcard model. Inside src/lib/models, create a file named Flashcard.ts and add the code below:

import mongoose, { Schema, model, models } from "mongoose";

export interface IFlashcard {
  _id: string;
  subjectId: string;
  front: string;
  back: string;
  createdAt: Date;
  updatedAt: Date;
}

const FlashcardSchema = new Schema(
  {
    subjectId: { type: Schema.Types.ObjectId, ref: "Subject", required: true },
    front: { type: String, required: true },
    back: { type: String, required: true },
  },
  { timestamps: true }
);

export default models.Flashcard || model<IFlashcard>("Flashcard", FlashcardSchema);

In this code:

• subjectId: References a Subject by its _id. ref: "Subject" lets Mongoose populate this field (replace the ID with the full subject object when we fetch).

• front and back: The question and answer text.

Progress Model

When a user studies, we need to record whether they answered each flashcard correctly or incorrectly. We'll use this information to display their progress on the dashboard.

Next, let's create the Progress model. Inside src/lib/models, create a file named Progress.ts and add the code below:

import mongoose, { Schema, model, models } from "mongoose";

export interface IProgress {
  _id: string;
  flashcardId: string;
  subjectId: string;
  correct: boolean;
  reviewedAt: Date;
}

const ProgressSchema = new Schema(
  {
    flashcardId: { type: Schema.Types.ObjectId, ref: "Flashcard", required: true },
    subjectId: { type: Schema.Types.ObjectId, ref: "Subject", required: true },
    correct: { type: Boolean, required: true },
    reviewedAt: { type: Date, default: Date.now },
  },
  { timestamps: true }
);

export default models.Progress || model<IProgress>("Progress", ProgressSchema);

In this code:

• correct: true if the user knew the answer, false if not.

• reviewedAt: When the review happened. We use this for sorting and future features like spaced repetition.

Subjects API – List and Create

Now that we've defined our data models, let's create the API routes that will allow the application to work with that data.

API routes handle requests from the frontend and communicate with MongoDB. In this section, we'll create routes for creating and retrieving subjects and flashcards.

We'll start with the subjects API. This route will support two operations:

• GET: Retrieve all subjects.

• POST: Create a new subject.

Inside src/app/api/subjects, create a file named route.ts and add the code below:

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Subject from "@/lib/models/Subject";

export async function GET() {
  try {
    await dbConnect();
    const subjects = await Subject.find({}).sort({ createdAt: -1 });
    return NextResponse.json(subjects);
  } catch (error) {
    console.error("Error fetching subjects:", error);
    return NextResponse.json(
      { error: "Failed to fetch subjects" },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    await dbConnect();
    const body = await request.json();
    const { name, description, color } = body;

    if (!name) {
      return NextResponse.json(
        { error: "Subject name is required" },
        { status: 400 }
      );
    }

    const subject = await Subject.create({
      name,
      description: description || "",
      color: color || "#6366f1",
    });

    return NextResponse.json(subject);
  } catch (error) {
    console.error("Error creating subject:", error);
    return NextResponse.json(
      { error: "Failed to create subject" },
      { status: 500 }
    );
  }
}

In this code:

• GET: Fetches all subjects, sorted by newest first. find({}) means "find all." Returns them as JSON.

• POST: Creates a new subject. Reads name, description, and color from the request body. Validates that name exists. Uses Subject.create() to save to MongoDB. Returns the created subject.

• status: 400: Bad request (missing data). status: 500: Server error (for example, database failure).

Flashcards API – List and Create

Next, let's create the API route for working with flashcards. This route will let us retrieve existing flashcards and create new ones.

Inside src/app/api/flashcards, create a file named route.ts and add the code block:

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Flashcard from "@/lib/models/Flashcard";

export async function GET(request: Request) {
  try {
    await dbConnect();
    const { searchParams } = new URL(request.url);
    const subjectId = searchParams.get("subjectId");

    const query = subjectId ? { subjectId } : {};
    const flashcards = await Flashcard.find(query)
      .populate("subjectId", "name color")
      .sort({ createdAt: -1 });

    return NextResponse.json(flashcards);
  } catch (error) {
    console.error("Error fetching flashcards:", error);
    return NextResponse.json(
      { error: "Failed to fetch flashcards" },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    await dbConnect();
    const body = await request.json();
    const { subjectId, front, back } = body;

    if (!subjectId || !front || !back) {
      return NextResponse.json(
        { error: "Subject, front, and back are required" },
        { status: 400 }
      );
    }

    const flashcard = await Flashcard.create({
      subjectId,
      front,
      back,
    });

    const populated = await Flashcard.findById(flashcard._id).populate(
      "subjectId",
      "name color"
    );

    return NextResponse.json(populated);
  } catch (error) {
    console.error("Error creating flashcard:", error);
    return NextResponse.json(
      { error: "Failed to create flashcard" },
      { status: 500 }
    );
  }
}

In this code:

• searchParams.get("subjectId"): For GET /api/flashcards?subjectId=abc123, we filter by that subject. If no subjectId, we return all flashcards.

• .populate("subjectId", "name color"): Replaces the raw ID with the subject object, but only includes name and color. Makes it easy to display the subject name in the UI.

• POST: Requires subjectId, front, and back. After creating, we fetch the flashcard again with populate so the response includes the subject details.

Part 4: Editing and Deleting (Dynamic API Routes)

For individual subjects and flashcards, we'll use dynamic routes. In Next.js, placing [id] in a folder name creates a route that can handle different IDs. For example, /api/subjects/123 and /api/subjects/456 can use the same route.

Subject API Route

Let's start by creating the dynamic route for individual subjects. This route will let us retrieve, update, or delete a subject.

Inside src/app/api/subjects/[id], create a file named route.ts and add the code below:

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Subject from "@/lib/models/Subject";
import Flashcard from "@/lib/models/Flashcard";
import Progress from "@/lib/models/Progress";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;
    const subject = await Subject.findById(id);

    if (!subject) {
      return NextResponse.json({ error: "Subject not found" }, { status: 404 });
    }

    return NextResponse.json(subject);
  } catch (error) {
    console.error("Error fetching subject:", error);
    return NextResponse.json(
      { error: "Failed to fetch subject" },
      { status: 500 }
    );
  }
}

export async function PUT(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;
    const body = await request.json();
    const { name, description, color } = body;

    const subject = await Subject.findByIdAndUpdate(
      id,
      { name, description, color },
      { new: true }
    );

    if (!subject) {
      return NextResponse.json({ error: "Subject not found" }, { status: 404 });
    }

    return NextResponse.json(subject);
  } catch (error) {
    console.error("Error updating subject:", error);
    return NextResponse.json(
      { error: "Failed to update subject" },
      { status: 500 }
    );
  }
}

export async function DELETE(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;

    await Flashcard.deleteMany({ subjectId: id });
    await Progress.deleteMany({ subjectId: id });
    const subject = await Subject.findByIdAndDelete(id);

    if (!subject) {
      return NextResponse.json({ error: "Subject not found" }, { status: 404 });
    }

    return NextResponse.json({ message: "Subject deleted" });
  } catch (error) {
    console.error("Error deleting subject:", error);
    return NextResponse.json(
      { error: "Failed to delete subject" },
      { status: 500 }
    );
  }
}

In this code:

• params: In Next.js 15+, params is a Promise. We await it to get { id: "abc123" }.

• findByIdAndUpdate(id, updates, { new: true }): Updates the document and returns the updated version. { new: true } means "return the new document, not the old one."

• DELETE: When we delete a subject, we also delete its flashcards and progress records. Otherwise we'd have orphaned data.

Flashcard by ID – Get, Update, Delete

Now, let's create the dynamic route for individual flashcards. This route will let us retrieve, update, or delete a flashcard.

Inside src/app/api/flashcards/[id], create a file named route.ts and add the code below:

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Flashcard from "@/lib/models/Flashcard";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;
    const flashcard = await Flashcard.findById(id).populate(
      "subjectId",
      "name color"
    );

    if (!flashcard) {
      return NextResponse.json(
        { error: "Flashcard not found" },
        { status: 404 }
      );
    }

    return NextResponse.json(flashcard);
  } catch (error) {
    console.error("Error fetching flashcard:", error);
    return NextResponse.json(
      { error: "Failed to fetch flashcard" },
      { status: 500 }
    );
  }
}

export async function PUT(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;
    const body = await request.json();
    const { front, back } = body;

    const flashcard = await Flashcard.findByIdAndUpdate(
      id,
      { front, back },
      { new: true }
    ).populate("subjectId", "name color");

    if (!flashcard) {
      return NextResponse.json(
        { error: "Flashcard not found" },
        { status: 404 }
      );
    }

    return NextResponse.json(flashcard);
  } catch (error) {
    console.error("Error updating flashcard:", error);
    return NextResponse.json(
      { error: "Failed to update flashcard" },
      { status: 500 }
    );
  }
}

export async function DELETE(
  _request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  try {
    await dbConnect();
    const { id } = await params;
    const flashcard = await Flashcard.findByIdAndDelete(id);

    if (!flashcard) {
      return NextResponse.json(
        { error: "Flashcard not found" },
        { status: 404 }
      );
    }

    return NextResponse.json({ message: "Flashcard deleted" });
  } catch (error) {
    console.error("Error deleting flashcard:", error);
    return NextResponse.json(
      { error: "Failed to delete flashcard" },
      { status: 500 }
    );
  }
}

Part 5: Progress Tracking API

When a user marks a flashcard as correct or incorrect during a study session, we need to save that result. We'll also use this data to calculate progress statistics, such as the percentage of correct answers for each subject.

Next, let's create the API route for tracking progress. Inside src/app/api/progress, create a file named route.ts and add the code below:

import { NextResponse } from "next/server";
import dbConnect from "@/lib/db";
import Progress from "@/lib/models/Progress";

export async function GET(request: Request) {
  try {
    await dbConnect();
    const { searchParams } = new URL(request.url);
    const subjectId = searchParams.get("subjectId");

    const query = subjectId ? { subjectId } : {};
    const progress = await Progress.find(query).sort({ reviewedAt: -1 });

    const stats = await Progress.aggregate([
      { $match: query },
      {
        $group: {
          _id: "$subjectId",
          total: { $sum: 1 },
          correct: { $sum: { $cond: ["$correct", 1, 0] } },
        },
      },
    ]);

    return NextResponse.json({ progress, stats });
  } catch (error) {
    console.error("Error fetching progress:", error);
    return NextResponse.json(
      { error: "Failed to fetch progress" },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  try {
    await dbConnect();
    const body = await request.json();
    const { flashcardId, subjectId, correct } = body;

    if (!flashcardId || !subjectId || typeof correct !== "boolean") {
      return NextResponse.json(
        { error: "flashcardId, subjectId, and correct are required" },
        { status: 400 }
      );
    }

    const progress = await Progress.create({
      flashcardId,
      subjectId,
      correct,
    });

    return NextResponse.json(progress);
  } catch (error) {
    console.error("Error recording progress:", error);
    return NextResponse.json(
      { error: "Failed to record progress" },
      { status: 500 }
    );
  }
}

In this code:

• aggregate: MongoDB's aggregation pipeline. We group by subjectId and count total reviews and correct answers. $cond: ["$correct", 1, 0] means "if correct is true, add 1, else add 0."

• stats: Returns something like [{ _id: "subjectId123", total: 20, correct: 16 }]. The frontend uses this to show "80% accuracy" per subject.

UI Implementation

Now we'll build the pages users see. We'll use React hooks (useState, useEffect) to manage data and fetch to call our API.

The Subjects Page

On load, we fetch subjects from the API. We show a form to create new subjects. Each subject is a card that links to its detail page.

Key logic:

1. useEffect runs once on mount and calls fetch("/api/subjects").

2. The form's onSubmit calls fetch("/api/subjects", { method: "POST", ... }).

3. After a successful create, we clear the form and call fetchSubjects() again to refresh the list.

// Simplified structure - see full code in src/app/subjects/page.tsx
const [subjects, setSubjects] = useState<Subject[]>([]);
const [showForm, setShowForm] = useState(false);

useEffect(() => {
  fetch("/api/subjects")
    .then((res) => res.json())
    .then((data) => setSubjects(data));
}, []);

const handleSubmit = async (e) => {
  e.preventDefault();
  await fetch("/api/subjects", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name, description, color }),
  });
  fetchSubjects(); 
};

The Subject Detail Page (Creating and Editing Flashcards)

This page shows one subject and its flashcards. Users can add new cards or edit/delete existing ones. The URL is /subjects/[id], so we use useParams() to get the subject ID.

Key logic:

1. useParams() gives us the id from the URL.

2. We fetch the subject and its flashcards on mount.

3. "Add Flashcard" shows a form. On submit, we POST to /api/flashcards with subjectId, front, and back.

4. Each card has Edit and Delete buttons. Edit switches to an inline form, while Delete calls DELETE /api/flashcards/[id].

// Creating a flashcard
const handleCreate = async (e) => {
  e.preventDefault();
  await fetch("/api/flashcards", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ subjectId: id, front, back }),
  });
  fetchFlashcards(); // Refresh
};

// Updating a flashcard
const handleUpdate = async (e) => {
  e.preventDefault();
  await fetch(`/api/flashcards/${editingId}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ front: editFront, back: editBack }),
  });
  setEditingId(null);
  fetchFlashcards();
};

The Study Page – Flipping Cards

The study page has three main states:

1. Subject selection: User picks which subject to study.

2. Ready to start: Shows "Start Studying" with the card count.

3. Studying: Shows one card at a time. User clicks to flip, then marks correct or wrong. We advance to the next card and record progress.

The Flip Animation

We use CSS 3D transforms to create the flip animation. The flashcard has two faces: a front for the question and a back for the answer. When flipped is true, we rotate the card container 180 degrees. We also use backface-visibility: hidden so that only the appropriate face is visible during the rotation.

To add the styles for the flip animation, open src/app/globals.css and add the following code:

/* Flashcard flip animation */
.perspective-1000 {
  perspective: 1000px;
}

.preserve-3d {
  transform-style: preserve-3d;
}

.backface-hidden {
  backface-visibility: hidden;
}

/* Lined paper effect for the card background */
.lined-paper {
  background-image: repeating-linear-gradient(
    transparent,
    transparent 27px,
    #e5e7eb 27px,
    #e5e7eb 28px
  );
}

The lined-paper class creates horizontal grey lines (like notebook paper) using a repeating gradient. This gives the flashcard a familiar, study-friendly look.

The card structure:

<div
  className={`preserve-3d transition-transform duration-500 ${
    flipped ? "[transform:rotateY(180deg)]" : ""
  }`}
>
  {/* Front face - Question */}
  <div className="backface-hidden [transform:rotateY(0deg)]">
    {currentCard.front}
  </div>
  {/* Back face - Answer */}
  <div className="backface-hidden [transform:rotateY(180deg)]">
    {currentCard.back}
  </div>
</div>

When the user clicks the card, we toggle flipped. The parent rotates, and the correct face becomes visible.

Recording Progress

When the user clicks "Got it!" or "Didn't know", we:

1. POST to /api/progress with flashcardId, subjectId, and correct.

2. Update local state (sessionCorrect or sessionWrong) for the live stats.

3. Move to the next card. If we've finished all cards, we show the "Start Studying" screen again.

const handleKnow = () => {
  recordProgress(true);
  setFlipped(false);
  if (currentIndex < flashcards.length - 1) {
    setCurrentIndex((i) => i + 1);
  } else {
    setStudyStarted(false);
    setCurrentIndex(0);
  }
};

The Progress Page

Here, we fetch subjects and progress stats. For each subject, we look up its stats (total reviews, correct count) and compute the percentage. We display overall stats at the top and per-subject breakdown below.

const getSubjectStats = (subjectId) => {
  const stat = stats.find((s) => s._id === subjectId);
  return stat
    ? {
        total: stat.total,
        correct: stat.correct,
        pct: Math.round((stat.correct / stat.total) * 100),
      }
    : null;
};

Optional: Lined Paper and Paperclip Icon

The app includes a lined-paper effect and a paperclip icon to make the flashcard feel more tactile. The paperclip is a simple SVG component:

// src/components/PaperclipIcon.tsx
export default function PaperclipIcon({ className }: { className?: string }) {
  return (
    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
      <path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48" />
    </svg>
  );
}

Place it at the top center of the flashcard. The lined-paper class is applied to the card content area for the notebook effect.

Best Practices

Code Organization

• Models in lib/models/: One file per model. Keeps schemas in one place.

• API routes in app/api/: Group by resource (subjects, flashcards, progress). Use [id] for dynamic routes.

• Reusable components: The PaperclipIcon is in components/. Use this pattern for any UI you repeat.

Error Handling

• API routes: Always wrap logic in try/catch. Return appropriate status codes (400 for bad input, 404 for not found, 500 for server errors).

• Frontend: Check res.ok before using res.json(). Show loading and error states to the user.

Performance Tips

• Database connection: Reuse the connection (our dbConnect does this). Don't connect on every request.

• Populate sparingly: Only .populate() fields you need. Specify which fields: .populate("subjectId", "name color").

• Loading states: Show a spinner while fetching. Prevents layout shift and gives feedback.

Conclusion

You've built a full-stack flashcard app with:

• Next.js for the app and API routes

• MongoDB + Mongoose for storing subjects, flashcards, and progress

• React for the UI with forms, lists, and a flip animation

• Tailwind CSS for styling

Possible Improvements

There are a few features you could build to improve this app.

First, you could add authentication. Add login so each user has their own subjects and cards. Consider NextAuth.js or Clerk.

Second, you could add a spaced repetition feature. Use the progress data to show cards at optimal intervals (for example, cards you got wrong more often).

Next, you could add some animations, like transitions between cards or a confetti effect when a session is complete.

You could also build in mobile responsiveness. The current layout works on desktop, but you could optimize the study view for phones.

And finally, an export/import feature could be useful: let users export their flashcards as JSON or CSV for backup.

Next Steps

To take this further, run npm run dev and explore the app. You can add a few subjects and flashcards, then try the study mode.

After that, open MongoDB Compass or Atlas to inspect your data. Experiment with the code: change colors, add fields, or tweak the flip animation.

Happy studying!

You run:

git add .
git commit -m "Fix API integration"
git push

A few minutes later, you notice something strange. Your API usage has suddenly increased. Maybe there are unexpected requests, new cloud resources, or even a bill that looks much larger than expected.

Then you find it:

const apiKey = "sk_live_123456789";

Your API key is sitting in a Git repository.

This situation is stressful, but it's fixable.

The most important rule is:

If an API key has been committed to Git, assume it has been copied and compromised, even if you delete it immediately.

Deleting the key from the latest version of your file doesn't make the old key safe. Git keeps previous versions of files in its history, and exposed credentials can be discovered by automated scanners.

In this guide, you'll learn the following:

• What Is an API Key?

• The Emergency Response: What to Do First

• Step 1: Revoke or Rotate the Leaked Key

• Step 2: Investigate Suspicious Activity

• Step 3: Remove the Secret From Your Current Code

• Step 4: Use a.envFile for Local Development

• Step 5: Create a Safe.env.example

• Step 6: Determine Whether the Secret Is Still in Git History

• When Do You Need to Rewrite Git History?

• Step 7: Remove the Secret From Git History

• Step 8: Verify That the Secret Is Gone

• Step 9: Push the Cleaned History Carefully

• Step 10: Replace the Credential Everywhere

• Step 11: Restrict the Replacement Key

• What About Frontend Applications?

• Environment Variables vs Secret Managers

• Add Secret Scanning to Your Workflow

• Use Git Hooks as an Extra Safety Net

• Review Your Staged Diff Before Committing

• Common Mistakes Developers Make

• A Complete API-Key Incident Checklist

• A Secure Project Structure

We'll use this basic workflow throughout the article:

Invalidate → Investigate → Remove → Replace → Prevent

Let's start with what an API key actually is before we get to the most important part: what to do right now after a key is exposed.

What Is an API Key?

An API key is a credential that allows an application to communicate with another service.

For example, an application might use an API key to access:

• A weather service

• A payment provider

• A mapping service

• An artificial intelligence API

• A cloud platform

• A database

• An email provider

• A private company API

A key might look something like this:

const apiKey = "your-real-api-key";

Or it might appear in a configuration file:

{
  "apiKey": "your-real-api-key",
  "databasePassword": "your-real-password"
}

API keys are often called secrets because possessing one may allow someone to make requests, access data, create resources, or generate charges on your account.

Not every API key is equally sensitive. Some services provide browser keys that are intentionally visible to users. Those keys should still have appropriate restrictions, quotas, and permissions.

As a general rule:

If a credential can access private data, create resources, modify records, or generate charges, it shouldn't be stored directly in your source code.

The Emergency Response: What to Do First

When you discover a leaked credential, a common reaction is to delete the key from the file and push another commit.

Don't start there.

Your first priority is to make the leaked credential useless.

Use this order of operations:

1. Invalidate the leaked credential
2. Investigate suspicious activity
3. Remove the secret from your code
4. Replace it with a new credential
5. Clean the Git history if necessary
6. Verify the cleanup
7. Add protections against future leaks

Think of an API key like a house key that was dropped in a crowded street.

Deleting a picture of the key doesn't matter if someone already picked up the physical key.

Change the lock first.

Step 1: Revoke or Rotate the Leaked Key

Go to the dashboard of the service that issued the credential.

Depending on the provider, you may see options such as:

• Revoke

• Delete

• Disable

• Rotate

• Regenerate

• Create new key

If the provider supports key rotation, create a replacement credential before disabling the old one if possible. This can reduce application downtime while you update your configuration.

The important thing is that the original credential must no longer be usable.

Do not reuse the leaked key. Don't rename it. Don't encode it. Don't move it to another file and assume it is safe. Don't assume nobody saw it.

Treat it as compromised.

Step 2: Investigate Suspicious Activity

After disabling the credential, check the provider's usage dashboard and logs.

Look for things such as:

• Sudden spikes in requests

• Requests from unfamiliar locations

• Unexpected database queries

• New cloud resources

• Changes to permissions

• Unexpected downloads

• Unusual payment activity

• New deployments

• Requests at times when your application was inactive

If the credential had broad permissions, assume that anything within its permission scope MAY have been accessed or modified.

For example, if a cloud credential could create virtual machines, check whether unexpected machines were created.

If a credential could access a database, review:

• Authentication logs

• Read operations

• Write operations

• Deleted records

• Exported data

• Newly created accounts

• Permission changes

Also check your billing information if the credential could generate usage-based charges.

Write down what you discover. A simple timeline can help:

10:15 - API key committed
10:23 - Repository pushed publicly
10:41 - Unusual usage detected
10:45 - Key revoked
11:00 - Logs reviewed
11:30 - Replacement key deployed
12:00 - Git history cleaned

This can be especially useful if you need to report the incident to a team or service provider.

Step 3: Remove the Secret From Your Current Code

Once the original credential has been disabled, remove it from your working files.

This is unsafe:

const apiKey = "your-real-api-key";

Instead, load the credential from the environment:

const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error("API_KEY is not configured");
}

In Python:

import os

api_key = os.environ.get("API_KEY")

if not api_key:
    raise RuntimeError("API_KEY is not configured")

The important idea is simple:

Source code → environment variable → secret value

instead of:

Source code → hardcoded secret

Environment variables aren't the only way to manage secrets, but they are a common and practical solution for local development and many deployment environments.

Step 4: Use a .env File for Local Development

For local development, you can store environment variables in a .env file.

For example:

API_KEY=your-local-development-key
DATABASE_URL=your-local-database-url

A Node.js project can load these values with a package such as dotenv.

Install it with:

npm install dotenv

Then:

import "dotenv/config";

const apiKey = process.env.API_KEY;

The important part is that the .env file normally should not be committed to Git.

Add it to .gitignore:

# Environment files
.env
.env.*
!.env.example

# Credential files
*.pem
*.key
credentials.json
service-account.json

# Local development files
.DS_Store

But there's an important detail here: the .gitignore does NOT remove files that Git is already tracking.

If .env has already been committed, adding it to .gitignore won't erase it from Git.

You can stop tracking the file while keeping it on your computer:

git rm --cached .env

Then commit the .gitignore change:

git add .gitignore
git commit -m "Ignore local environment files"

But remember: this only removes the file from future commits. It does not remove the secret from previous commits.

That's where Git history comes in.

Step 5: Create a Safe .env.example

Other developers still need to know which environment variables the application requires.

Instead of committing .env, create .env.example:

API_KEY=
DATABASE_URL=
PORT=3000
LOG_LEVEL=info

This file contains variable names rather than real credentials, so it can be committed to the repository.

You can also provide comments:

# Required API credential
API_KEY=

# PostgreSQL connection string
DATABASE_URL=

# Optional application port
PORT=3000

A new developer can then copy the file:

cp .env.example .env

and provide their own values.

Use clearly fake placeholders in examples:

API_KEY=replace-me-with-your-own-key

Avoid putting realistic-looking production credentials into .env.example.

Step 6: Determine Whether the Secret Is Still in Git History

This is one of the most important parts of fixing a leaked credential.

Suppose your Git history looks like this:

Commit A: Add API key to config.js
Commit B: Update API integration
Commit C: Delete API key

Even though Commit C no longer contains the key, Commit A still does.

Git remembers previous versions of your files.

You can inspect the history of a file with:

git log --all -- config.js

To display a file from an older commit:

git show COMMIT_ID:config.js

You can also search Git history for a known leaked value:

git log --all -S"your-leaked-key" --oneline

If you know the secret was committed, you should assume that it exists somewhere in the repository's history until you've verified otherwise.

When Do You Need to Rewrite Git History?

Not every accidental secret requires a history rewrite. Consider these situations:

The Secret Was Never Committed

If the secret exists only in your working directory and was never committed, you generally don't need to rewrite history.

Remove it, add the appropriate file to .gitignore, and continue.

The Secret Was Committed Locally But Never Pushed

If the secret exists in local commits but hasn't been shared with a remote repository, you may be able to clean up those commits before pushing.

The Secret Was Pushed to a Remote Repository

Treat the credential as compromised. Revoke or rotate it immediately.

Then determine whether removing the secret from the repository's history is appropriate.

The Repository Was Public

Assume that someone or something may already have copied the secret.

This is why revocation comes before Git cleanup.

The Secret Was in a Private Repository

A private repository is safer than a public repository, but it isn't a secret vault.

Credentials can still escape through:

• Compromised accounts

• Contractors

• Integrations

• CI logs

• Forks

• Backups

• Screenshots

• Copied code

• Pull requests

So the safest rule remains:

Never intentionally commit credentials to Git, even in a private repository.

Step 7: Remove the Secret From Git History

If the credential was committed, you may need to remove it from the repository's history.

Before rewriting history, create a backup:

git clone --mirror https://github.com/your-username/your-repository.git repository-backup.git

A mirror clone includes branches and tags, which makes it useful for recovery if something goes wrong.

Option 1: Remove an Entire File

If the secret was stored in a file such as .env, you can remove that file from the entire history:

git filter-repo --path .env --invert-paths

For a file inside a directory:

git filter-repo --path config/production.json --invert-paths

This removes the file from the repository's rewritten history.

Option 2: Replace a Secret Inside a File

Sometimes you need to keep the file but remove the secret from previous versions.

Create a temporary replacements file:

Then run:

git filter-repo --replace-text replacements.txt

You can replace the value with a placeholder:

your-leaked-key==>YOUR_API_KEY_HERE

Be extremely careful with replacements.txt. It contains the original secret, so do not commit it.

Delete it after the cleanup:

rm replacements.txt

On Windows PowerShell:

Remove-Item replacements.txt

For multiple secrets:

old-api-key==>REMOVED_API_KEY
old-database-password==>REMOVED_DATABASE_PASSWORD
old-token==>REMOVED_TOKEN

Then:

git filter-repo --replace-text replacements.txt

Test the cleanup on your backup clone first.

Step 8: Verify That the Secret Is Gone

Never assume the cleanup worked just because the command completed successfully.

Search for the known leaked value again:

git log --all -S"your-leaked-key" --oneline

You can also inspect relevant files and commits:

git log --all -- config.js

and:

git show COMMIT_ID:config.js

If your repository uses branches and tags, make sure you aren't checking only the branch you currently have checked out.

You should also inspect other locations where the secret may have appeared, including pull requests, CI/CD logs, build artifacts, release files, Docker images, package releases, documentation, issue comments, and screenshots

Remember:

Rewriting your repository doesn't erase copies that already exist somewhere else.

That's another reason why the original credential must be revoked.

Step 9: Push the Cleaned History Carefully

Once you've verified the cleanup, you may need to push the rewritten history:

git push --force --all origin
git push --force --tags origin

Important Warning

Force-pushing rewritten history is disruptive. It changes commit hashes and can affect collaborators who have existing clones of the repository.

Before doing this on a shared project:

1. Tell your collaborators.

2. Make sure everyone understands that history is being rewritten.

3. Coordinate the cleanup.

4. Follow your organization's incident-response process if one exists.

After the rewrite, collaborators may need to reclone the repository:

git clone https://github.com/your-username/your-repository.git

They shouldn't blindly merge their old repository history back into the cleaned repository.

Step 10: Replace the Credential Everywhere

Now create or use the replacement credential. Update every environment where the application runs. Common locations include:

• Local development

• Testing

• Staging

• Production

• Docker containers

• Kubernetes secrets

• CI/CD systems

• Hosting platforms

• Scheduled jobs

• Serverless functions

A common mistake is updating production but forgetting the deployment pipeline.

For example, your local application may work because .env contains the new key, while your CI/CD system still contains the old one.

Make a checklist:

1. Local development
2. Automated tests
3. Staging
4. Production
5. CI/CD variables
6. Docker configuration
7. Cloud deployment settings
8. Scheduled scripts
9. Serverless functions

After updating the credential, test the application in each important environment.

Step 11: Restrict the Replacement Key

Replacing a leaked credential is only part of the solution.

The new credential should have only the permissions it actually needs.

Useful restrictions can include:

• Read-only permissions

• Specific API scopes

• Allowed IP addresses

• Allowed domains

• Environment-specific access

• Request quotas

• Rate limits

• Expiration dates

For example, a weather application may only need permission to read weather data.

It shouldn't have permission to manage users, modify billing, or delete unrelated resources.

This is the principle of least privilege:

Give each credential the smallest amount of access necessary to perform its job.

It's also a good idea to use different credentials for different environments:

local-development-key
testing-key
staging-key
production-key

That way, a development credential leak doesn't automatically expose production resources.

What About Frontend Applications?

This is where API-key security gets confusing.

Frontend code runs on the user's device.

That means users can inspect it.

For example:

const apiKey = "browser-key";

A user can inspect the JavaScript bundle, browser developer tools, or network requests and potentially see the value.

Some services intentionally provide browser API keys that are designed to be publicly visible.

Those keys should still be restricted by things such as:

• Allowed domains

• Website origins

• API operations

• Usage quotas

• Referrer restrictions

• Time limits

But a truly private credential should never be placed in browser code.

Instead of:

fetch("https://private-api.example.com/data", {
  headers: {
    Authorization: "Bearer private-secret-token"
  }
});

have the browser call your own backend:

fetch("/api/data");

Then the backend communicates with the private service:

const response = await fetch(
  "https://private-api.example.com/data",
  {
    headers: {
      Authorization: `Bearer ${process.env.PRIVATE_API_TOKEN}`
    }
  }
);

The backend can then return only the information the browser is allowed to receive.

The important distinction is:

Public/browser credential
        ↓
Can be visible, but should be restricted

Private credential
        ↓
Must remain on a trusted backend or secret-management system

Environment Variables vs Secret Managers

Environment variables are useful, but they're not a universal secret-management solution.

For a small application or local development environment, something like:

API_KEY=your-secret

may be perfectly reasonable.

For larger production systems, you may want a dedicated secret manager.

A secret-management system can provide features such as:

• Centralized credential storage

• Access controls

• Auditing

• Credential rotation

• Versioning

• Separation between environments

• Integration with deployment systems

The important idea is that your source code shouldn't be responsible for storing production secrets.

Instead:

Application
    ↓
Secret management system
    ↓
Credential

rather than:

Application
    ↓
Hardcoded production credential

Which solution you use depends on the size and requirements of your project.

Add Secret Scanning to Your Workflow

Humans are excellent programmers and occasionally terrible search engines.

Automated secret scanning can catch credentials before they make it into a repository.

Popular tools include:

• Gitleaks

• TruffleHog

• detect-secrets

• Pre-commit hooks

• Git hosting secret scanning

• CI security scanners

For example, you can run Gitleaks locally:

gitleaks detect --source . --verbose

You can also integrate secret scanning into CI.

A basic GitHub Actions workflow might look like this:

name: Secret Scan

on:
  push:
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Scan for secrets
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Review the documentation for your chosen tool and pin versions according to your project's security practices.

Secret scanners can produce false positives, so you may need to configure exceptions for safe test values.

Be careful with allowlists, though. An overly broad exception can hide a real credential.

Use Git Hooks as an Extra Safety Net

You can also scan files before they're committed.

For example, a simple pre-commit script could search for suspicious words:

#!/usr/bin/env bash

if grep -RniE "api[_-]?key|password|secret|token|private[_-]?key" . \
  --exclude-dir=.git \
  --exclude=".env.example"; then

  echo "Possible secret detected. Commit cancelled."
  exit 1
fi

This isn't a complete security scanner, but it can catch obvious mistakes.

For stronger protection, use a dedicated secret-scanning tool through a pre-commit framework.

The goal isn't to make committing miserable. The goal is to make accidentally publishing a credential harder.

Review Your Staged Diff Before Committing

One of the simplest security habits you can develop is checking what you're actually about to commit.

First:

git status

Then stage only the files you intend to commit:

git add src/api.js README.md

Now inspect the staged changes:

git diff --cached

Look for:

• API keys

• Passwords

• Tokens

• Private URLs

• Internal hostnames

• Customer data

• Debug output

• Personal information

• Private certificates

Only commit after the staged diff looks correct:

git commit -m "Load API key from environment"

Be cautious with:

git add .

It can stage files you never intended to publish, including .env files, database exports, generated files, or local configuration.

Common Mistakes Developers Make

Mistake 1: "I Deleted It, So It's Fine"

Deleting a secret from the current version of a file doesn't delete it from Git history.

Correct response: Revoke the credential and clean the repository history when appropriate.

Mistake 2: "The Repository Is Private"

Private repositories aren't vaults.

Credentials can still escape through compromised accounts, integrations, CI logs, forks, backups, or copied code.

Correct response: Don't commit secrets even to private repositories.

Mistake 3: "I'll Just Encode It"

These don't make a credential secret:

const key = atob("c29tZS1rZXk=");

or:

const key = "some-" + "secret-" + "value";

Encoding, splitting, renaming, or hiding a credential doesn't protect it.

If your application can reconstruct the credential, someone analyzing the application may be able to do the same.

Mistake 4: Logging the Secret

Don't do this:

console.log(process.env.API_KEY);

Logs can be stored by your terminal, CI system, hosting provider, monitoring platform, or cloud service.

Instead:

console.log(
  "API key configured:",
  Boolean(process.env.API_KEY)
);

If you absolutely need to inspect a value during debugging, avoid printing the full credential.

For example:

function maskSecret(value) {
  if (!value) return "not configured";
  if (value.length <= 8) return "********";

  return `${value.slice(0, 4)}...${value.slice(-4)}`;
}

console.log(maskSecret(process.env.API_KEY));

Even masked credentials should be handled carefully.

Mistake 5: Using the Same Credential Everywhere

If local development, testing, staging, and production all use the same credential, one leak can affect everything.

Correct response: Use separate credentials with separate permissions.

Mistake 6: Cleaning Only the Current Branch

A secret can remain in:

• Old branches

• Tags

• Pull requests

• Other references

Correct response: Consider the entire repository when investigating and cleaning a leaked credential.

Mistake 7: Forgetting Build Artifacts

A secret might also appear in:

• Compiled JavaScript bundles

• Docker images

• Downloadable releases

• Published packages

• Generated documentation

Correct response: Revoke the credential and identify affected artifacts that may need to be removed or replaced.

A Complete API-Key Incident Checklist

If you discover that you've exposed an API key, use this checklist:

1. Revoke or rotate the leaked key
2. Create a replacement credential
3. Restrict the replacement credential
4. Review provider logs
5. Review billing and usage
6. Check for unauthorized resources
7. Remove the key from current files
8. Add secret files to .gitignore
9. Create or update .env.example
10. Search Git history
11. Check branches and tags
12. Remove the secret from Git history if necessary
13. Verify the old secret is gone
14. Force-push cleaned history if appropriate
15. Check pull requests and forks
16. Check CI and deployment logs
17. Update local configuration
18. Update staging configuration
19. Update production configuration
20. Update CI/CD secrets
21. Run a secret scanner
22. Document the incident
23. Add preventive security checks

The exact steps will depend on your provider and project, but the order matters: Invalidate first. Clean up second.

A Secure Project Structure

A simple Node.js project might look like this:

my-project/
├── src/
│   └── api.js
├── .env
├── .env.example
├── .gitignore
├── package.json
└── README.md

The local .env file contains the actual development value:

API_KEY=your-local-key

The .env.example file contains no real credential:

API_KEY=replace-me-with-your-own-key

The application reads the environment variable:

import "dotenv/config";

const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error("Missing API_KEY environment variable");
}

export async function getData() {
  const response = await fetch(
    "https://api.example.com/data",
    {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    }
  );

  if (!response.ok) {
    throw new Error(
      `API request failed: ${response.status}`
    );
  }

  return response.json();
}

And .gitignore keeps the local environment file out of future commits:

.env
.env.*
!.env.example

node_modules/

Finally, your README can explain the setup without exposing credentials:

Step 1: Copy the example environment file on your bash cp .env.example .env

Step 2: Add your own API key to .env.

And last but not least, start your application!

npm start

Final Thoughts

Leaking an API key doesn't mean you're a terrible developer. It just means your development workflow needs better guardrails.

The important thing is knowing how to respond quickly and how to prevent the same mistake from happening again.

Remember the emergency formula:

Invalidate → Investigate → Remove → Replace → Prevent

The important thing is knowing how to respond quickly and how to prevent the same mistake from happening again.

• Invalidate the leaked credential so it can no longer be used.

• Investigate your logs, usage, and billing to determine whether it was abused.

• Remove the secret from your current code and, when necessary, from Git history.

• Replace it with a new credential that has only the permissions it needs.

• Prevent future leaks with environment variables, secret managers, secret scanning, and careful Git practices.

Git is excellent at remembering your project's history. That's useful when you accidentally delete an important function. But it's much less useful when that history contains a password.

So keep your code public when appropriate. And keep your secrets somewhere else.

Happy coding!

A lot of modern AI systems rely on something called a neural network.

Now, the name can make them sound much more complicated than they really are. You might imagine that you need advanced calculus, a huge computer, and thousands of lines of code to build one.

You don't.

At its most basic level, a neural network is a mathematical model that takes some numbers as input, performs calculations on those numbers, makes a prediction, checks how far that prediction was from the correct answer, and then adjusts itself so it can do a little better next time.

In this tutorial, we're going to build one ourselves using Python and NumPy.

Here's What We'll Cover:

• 1. What Is a Neural Network?

• 2. Why Are They Called Neural Networks?

• 3. The Three Main Parts of a Neural Network

• 4. What Is a Neuron?

• 5. What Is a Weight?

• 6. What Is a Bias?

• 7. Why Do We Need Activation Functions?

• 8. Building Our First Neuron in Python

• 9. From One Neuron to a Layer

• 10. How Does a Neural Network Actually Learn?

• 11. Predictions and Loss

• 12. What Are Gradients?

• 13. What Is Gradient Descent?

• 14. What Is Backpropagation?

• 15. The Complete Learning Cycle

• 16. Let's Build a Neural Network From Scratch

• 17. Understanding the Network Architecture

• 18. Setting Up the Data

• 19. Creating the Weights and Biases

• 20. The Sigmoid Function

• 21. Forward Propagation

• 22. Calculating the Loss

• 23. Backpropagation in Code

• 24. Updating the Weights

• 25. The Complete NumPy Neural Network

• 26. Testing the Network

• 27. Why Did We Need a Hidden Layer?

• 28. What Happens in a Larger Neural Network?

• 29. Do You Have to Build Neural Networks From Scratch?

• 30. Building the Same Network With PyTorch

• 31. Training the Network With PyTorch

• 32. NumPy vs. PyTorch

• 33. What Is Deep Learning?

• 34. Where Are Neural Networks Used?

• 35. The Whole Process in One Picture

• 36. The Most Important Ideas to Remember

• 37. What Should You Learn Next?

• Final Takeaway

We'll start with a single artificial neuron, then gradually put together a complete neural network. By the end, you'll understand what weights and biases are, what activation functions do, how a network learns from its mistakes, what backpropagation and gradient descent actually mean, and how all of those pieces fit together.

You don't need to know advanced machine learning to follow along. Some basic Python and algebra will help, but I'll explain the important math as we go.

1. What Is a Neural Network?

Let's start with a simple example.

Imagine that we want a computer to predict whether a student will pass an exam.

We could give the computer information such as:

• How many hours the student studied

• How many practice questions they completed

• Their previous test score

For example:

Study Hours = 5 Practice Questions = 80 Previous Score = 82

We also know whether the student actually passed:

Passed = 1

After seeing many examples like this, we want the computer to learn a pattern.

Maybe students who study more tend to perform better. Maybe previous test scores are useful. Maybe practice questions are helpful, too.

Instead of writing all of those rules ourselves, we can give the examples to a neural network and let it learn the relationships.

The basic idea looks like this:

The prediction could be something like: 0.92

If we're predicting the probability of passing, we could interpret that as approximately a 92% predicted chance of passing.

The important thing is that we didn't tell the network that...

"Study hours are important, and previous scores are slightly more important."

Instead, the network learns numbers called weights that determine how strongly different inputs affect its predictions.

2. Why Are They Called Neural Networks?

The name comes from biological brains.

Your brain contains neurons that receive signals, process information, and pass signals to other neurons.

Artificial neural networks are not artificial brains. They don't work exactly like biological neurons. But the general idea of connecting many simple processing units inspired the name.

A very simplified artificial neuron looks like this:

The neuron receives numbers, performs some mathematical operations, and produces another number.

A neural network is made by connecting many of these artificial neurons together.

3. The Three Main Parts of a Neural Network

A simple neural network can be divided into three types of layers:

1. Input Layer

2. Hidden Layer(s)

3. Output Layer

Let's look at each one.

The Input Layer

The input layer contains the information we give the network.

For our student example, we could have three inputs:

Input 1 = Study Hours
Input 2 = Practice Questions
Input 3 = Previous Score

So one student's input might look like:

[5, 80, 82]

The network doesn't necessarily understand that these numbers mean "study hours" or "test score." To the mathematical part of the network, they're simply numbers.

That's an important idea to remember:

Neural networks work with numbers.

Images, text, audio, and other information must eventually be represented as numbers before a neural network can process them.

Hidden Layers

After the input layer come the hidden layers.

A network might look like:

The hidden layer contains neurons that perform calculations on the inputs.

A network can have one hidden layer or many hidden layers.

When a network has many layers, we often call it a deep neural network.

The Output Layer

The output layer produces the final result.

For a simple yes/no problem, we might represent the answers as:

0 = No
1 = Yes

For example:

0.12 → probably No
0.91 → probably Yes

For a problem with multiple categories, the output could contain several numbers:

Cat  = 0.05
Dog  = 0.90
Bird = 0.05

The largest value is associated with "Dog," so the model would predict Dog.

4. What Is a Neuron?

Now let's zoom in on one neuron.

Suppose our neuron receives three inputs:

x₁
x₂
x₃

Each input has a corresponding weight:

w₁
w₂
w₃

The neuron multiplies each input by its weight and adds the results together.

It also adds something called a bias.

The equation is:

z = x₁w₁ + x₂w₂ + x₃w₃ + b

Don't worry if that equation looks intimidating.

It's basically just:

input × weight
+
input × weight
+
input × weight
+
bias

Let's use actual numbers.

Suppose:

x₁ = 2
x₂ = 3
x₃ = 4

w₁ = 0.5
w₂ = 0.2
w₃ = 0.8

b = 1

Then:

z = (2 × 0.5) + (3 × 0.2) + (4 × 0.8) + 1

Calculate each part:

2 × 0.5 = 1.0
3 × 0.2 = 0.6
4 × 0.8 = 3.2

Now add them:

z = 1.0 + 0.6 + 3.2 + 1
z = 5.8

The neuron has produced 5.8.

But we're not finished yet.

5. What Is a Weight?

A weight controls how strongly an input affects a neuron.

Imagine we have:

x = 5

If the weight is:

w = 2

then:

x × w = 5 × 2
      = 10

But if the weight is:

w = 0.1

then:

x × w = 5 × 0.1
      = 0.5

The same input produced a very different result because the weight changed.

You can think of a weight as a volume knob.

A large positive weight makes an input have a stronger positive influence. A weight close to zero makes the input have little influence. A negative weight can push the result in the opposite direction.

The network learns these weights during training.

6. What Is a Bias?

The bias is another number added to the neuron's calculation.

Without the bias, we would have:

z = x₁w₁ + x₂w₂ + x₃w₃

With the bias:

z = x₁w₁ + x₂w₂ + x₃w₃ + b

Why add another number? Because it gives the neuron more flexibility.

Think of it like adjusting the starting point of the neuron's calculation.

The network learns the bias during training just like it learns the weights.

So when you see:

weights + bias

you're looking at some of the parameters the neural network can change while it learns.

7. Why Do We Need Activation Functions?

At this point, our neuron can calculate a weighted sum:

z = x₁w₁ + x₂w₂ + ... + b

But neural networks need to learn more complicated relationships than simple weighted sums.

That's where activation functions come in. An activation function takes the neuron's calculated value and transforms it.

One common activation function is ReLU. ReLU stands for Rectified Linear Unit.

Its equation is:

ReLU(x) = max(0, x)

In simple terms:

• If the number is positive, keep it.

• If the number is negative, turn it into zero.

For example:

ReLU(-5) = 0
ReLU(-2) = 0
ReLU(0)  = 0
ReLU(3)  = 3
ReLU(10) = 10

In Python:

def relu(x):
    return max(0, x)

With NumPy arrays, we can use:

def relu(x):
    return np.maximum(0, x)

Activation functions are important because they allow neural networks with multiple layers to learn more complicated patterns.

8. Building Our First Neuron in Python

Let's turn the math into Python.

First, import NumPy:

import numpy as np

NumPy gives us tools for working with numbers, arrays, vectors, and matrices.

Now let's create our inputs:

x = np.array([2, 3, 4])

This creates an array containing three values:

[2, 3, 4]

Now create the weights:

weights = np.array([0.5, 0.2, 0.8])

We have one weight for each input:

x₁ = 2    w₁ = 0.5
x₂ = 3    w₂ = 0.2
x₃ = 4    w₃ = 0.8

Next, create the bias:

bias = 1

Now we calculate the weighted sum:

z = np.dot(x, weights) + bias

np.dot() performs the multiplication-and-addition operation we described earlier.

In this case:

np.dot(x, weights)

is equivalent to:

(2 × 0.5) + (3 × 0.2) + (4 × 0.8)

which equals:

4.8

Then we add the bias:

4.8 + 1 = 5.8

Now apply ReLU:

output = np.maximum(0, z)

Since z is 5.8, ReLU leaves it unchanged:

output = 5.8

Finally:

print(output)

prints:

5.8

So our entire neuron is:

import numpy as np

x = np.array([2, 3, 4])
weights = np.array([0.5, 0.2, 0.8])
bias = 1

z = np.dot(x, weights) + bias
output = np.maximum(0, z)

print(output)

We have just created a tiny artificial neuron.

9. From One Neuron to a Layer

One neuron isn't enough for most interesting problems.

Instead, we can connect several neurons together.

For example:

Those neurons together form a layer.

A small neural network might look like:

Input Layer
     ↓
Hidden Layer
     ↓
Output Layer

Every neuron in one layer can send its output to neurons in the next layer.

This is where neural networks start becoming much more powerful.

10. How Does a Neural Network Actually Learn?

So far, we've manually chosen the weights:

0.5
0.2
0.8

But a real neural network doesn't start out knowing the correct weights.

Instead, it starts with weights that are usually initialized to small random values.

Then it goes through a cycle:

Make a prediction
       ↓
Compare prediction with correct answer
       ↓
Measure the error
       ↓
Figure out how to change the weights
       ↓
Update the weights
       ↓
Try again

This process happens over and over, and the network gradually adjusts its parameters to make better predictions on the training data.

Let's break each part down.

11. Predictions and Loss

Suppose the correct answer is:

1

but our network predicts:

0.3

The prediction isn't very close to the target.

We need a way to measure how wrong it is. That's what a loss function does.

A loss function takes the prediction and the correct answer and produces a number representing the model's error.

For a simple example, we could use squared error:

Loss = (prediction - actual)²

Using our numbers:

Loss = (0.3 - 1)²

First:

0.3 - 1 = -0.7

Then square it:

(-0.7)² = 0.49

So:

Loss = 0.49

Generally, a smaller loss means the prediction is closer to the target.

In real neural networks, different problems use different loss functions. For binary classification, binary cross-entropy is commonly used.

12. What Are Gradients?

Now we have a problem.

We know that the prediction was wrong, but how should we change the weights?

This is where gradients become useful. A gradient tells us how changing a parameter would affect the loss.

You can think of it like standing on a hill. Imagine that your goal is to reach the lowest point. If you know which direction slopes upward, you can move in the opposite direction to go downhill.

Training a neural network works with a similar idea. We want to reduce the loss. The gradients give us information about which direction the parameters should move.

13. What Is Gradient Descent?

Gradient descent is the process of using gradients to adjust the network's parameters.

A simplified update rule is:

new weight = old weight - learning rate × gradient

In Python:

weight = weight - learning_rate * gradient

The learning rate controls how large the update is.

For example:

learning_rate = 0.01

If the learning rate is too large, the network can make huge changes and potentially jump around instead of settling on a good solution.

If it's too small, learning can take a very long time.

So training involves finding parameter updates that move the model toward lower loss without making the process unstable.

14. What Is Backpropagation?

There's still one important question:

If a neural network has thousands or millions of weights, how does it figure out which weights contributed to the error?

That's where backpropagation comes in. Backpropagation calculates gradients for the parameters by working backward through the network.

Imagine a network like this:

Input
  ↓
Hidden Layer
  ↓
Output
  ↓
Loss

During the forward pass, information moves:

Input → Hidden Layer → Output

During backpropagation, gradient information moves backward:

Loss → Output → Hidden Layer → Input

The network uses these gradients to determine how its weights and biases should change.

You don't normally calculate all of these derivatives by hand when building real neural networks. Libraries such as PyTorch can calculate them automatically.

But understanding the basic idea is important:

Backpropagation calculates how the parameters contributed to the error, and gradient descent uses that information to update them.

15. The Complete Learning Cycle

Now we can put everything together.

More specifically:

Give the network data
          ↓
Calculate a prediction
          ↓
Compare it with the correct answer
          ↓
Calculate the loss
          ↓
Calculate gradients
          ↓
Update weights and biases
          ↓
Repeat

One complete pass through the training data is often called an epoch.

For example:

Epoch 1 → Loss: 0.82
Epoch 2 → Loss: 0.61
Epoch 3 → Loss: 0.43
Epoch 4 → Loss: 0.29
Epoch 5 → Loss: 0.18

These numbers are just an example, but ideally the loss decreases as training progresses.

16. Let's Build a Neural Network From Scratch

Congrats! You now understand the basics of neural networks. Now it's time to put these ideas together.

We're going to build a small neural network using only:

Python + NumPy

Our network will learn a classic machine learning problem called XOR.

XOR is a logical operation with two inputs.

Its rules are:

0 XOR 0 → 0
0 XOR 1 → 1
1 XOR 0 → 1
1 XOR 1 → 0

In other words, the output is 1 when exactly one of the inputs is 1.

Our training data will therefore be:

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

And the correct answers are:

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

We want our neural network to learn this pattern.

17. Understanding the Network Architecture

Our network will contain:

2 input neurons
       ↓
4 hidden neurons
       ↓
1 output neuron

The two inputs represent the two numbers in each XOR example.

The four hidden neurons give the network enough flexibility to learn the XOR relationship.

The output neuron produces a number between 0 and 1.

18. Setting Up the Data

Let's start our Python program.

import numpy as np

This imports NumPy. We'll use NumPy for arrays, matrix multiplication, and mathematical operations.

Next:

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

X contains our four training examples.

Each row is one example:

[0, 0]
[0, 1]
[1, 0]
[1, 1]

Now create the correct answers:

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

The first row of X corresponds to the first row of y.

So:

[0, 0] → 0
[0, 1] → 1
[1, 0] → 1
[1, 1] → 0

19. Creating the Weights and Biases

Now we need the parameters of our network.

First:

np.random.seed(42)

This makes our random numbers reproducible.

Without this line, the network would receive different random starting weights each time we ran the program.

Now create the first layer's weights:

W1 = np.random.randn(2, 4)

Why (2, 4)?

Because:

• We have 2 input values.

• We have 4 neurons in the hidden layer.

So W1 needs a weight connecting each input to each hidden neuron.

There are:

2 × 4 = 8

weights.

Next:

b1 = np.zeros((1, 4))

This creates four biases, one for each hidden neuron.

Now the second layer:

W2 = np.random.randn(4, 1)

There are four hidden neurons and one output neuron, so we need:

4 × 1 = 4

weights.

Finally:

b2 = np.zeros((1, 1))

This gives the output neuron one bias.

Our network parameters are therefore:

W1 → input-to-hidden weights
b1 → hidden-layer biases

W2 → hidden-to-output weights
b2 → output-layer bias

20. The Sigmoid Function

Our output represents a probability, so we'd like it to be between 0 and 1.

We can use the sigmoid function.

Its equation is:

sigmoid(x) = 1 / (1 + e⁻ˣ)

In Python:

def sigmoid(x):
    return 1 / (1 + np.exp(-x))

Let's see what it does:

sigmoid(-5) ≈ 0.007
sigmoid(0)  = 0.5
sigmoid(5)  ≈ 0.993

No matter how large or small the input is, the result stays between 0 and 1.

That's useful when our output represents a probability.

21. Forward Propagation

Now we can send the data through the network. This is called forward propagation.

First, calculate the hidden layer:

z1 = X @ W1 + b1

There's a new symbol here:

@

In Python, @ performs matrix multiplication.

You can think of this operation as performing many weighted sums at once.

Instead of manually calculating every neuron:

input × weight + input × weight + bias

NumPy can calculate all of them together.

The result is stored in z1.

Next:

a1 = np.tanh(z1)

Here we're using the tanh activation function for the hidden layer.

Tanh converts its input into values between -1 and 1.

Why use tanh here?

Because XOR isn't something a single simple linear calculation can solve. The nonlinear activation gives the hidden layer the flexibility it needs to learn the pattern.

Now calculate the output layer:

z2 = a1 @ W2 + b2

This takes the hidden layer's outputs and combines them using the second set of weights.

Finally:

a2 = sigmoid(z2)

Now a2 contains our predictions.

For example, before training, the network might produce something like:

0.52
0.61
0.48
0.55

Those predictions aren't useful yet, but that's expected. The network hasn't learned anything yet.

22. Calculating the Loss

Now we need to measure how good those predictions are.

For binary classification, we'll use binary cross-entropy, which is a loss function used in machine learning for binary classification. It measures the performance of a model whose output is a probability value between 0 and 1.

The formula is:

Loss = -mean(
    y × log(prediction)
    +
    (1 - y) × log(1 - prediction)
)

That looks much more complicated than the squared-error example from earlier, but we don't need to memorize the formula.

In Python:

loss = -np.mean(
    y * np.log(a2 + 1e-8) +
    (1 - y) * np.log(1 - a2 + 1e-8)
)

The 1e-8 is a very small number.

It prevents problems if a2 gets extremely close to 0 or 1, because taking the logarithm of exactly zero isn't valid.

At the beginning of training, the loss will probably be relatively high. But as the network learns, we'd like it to decrease.

23. Backpropagation in Code

Now comes the most mathematical part of our program.

We need to calculate the gradients.

Start with:

dz2 = a2 - y

This gives us the gradient of the loss with respect to the output layer's pre-activation value for the sigmoid + binary cross-entropy combination.

Next:

dW2 = (a1.T @ dz2) / len(X)

This calculates the gradient for W2.

The .T means transpose.

Our hidden-layer output has four neurons, while dz2 represents the output layer's error. Matrix multiplication combines them to determine how each hidden-to-output weight contributed to the loss.

We divide by:

len(X)

because we have four training examples and we're calculating the average gradient.

Now calculate the output bias gradient:

db2 = np.mean(dz2, axis=0, keepdims=True)

This calculates the average gradient for the output bias.

Next:

da1 = dz2 @ W2.T

This sends the gradient information backward from the output layer toward the hidden layer.

Now we need to account for the derivative of the tanh activation function.

The derivative of tanh can be written as:

1 - tanh(x)²

Since we already have the hidden layer's activated values in a1, we can write:

dz1 = da1 * (1 - a1**2)

This tells us how the hidden layer's pre-activation values affected the loss.

Now calculate the gradients for the first layer's weights:

dW1 = (X.T @ dz1) / len(X)

And the hidden-layer biases:

db1 = np.mean(dz1, axis=0, keepdims=True)

At this point, we have gradients for all of our trainable parameters.

24. Updating the Weights

Now we use gradient descent.

First:

W2 -= learning_rate * dW2

This updates the second layer's weights.

The -= means:

W2 = W2 - learning_rate * dW2

Then:

b2 -= learning_rate * db2

updates the output bias.

And:

W1 -= learning_rate * dW1

updates the first layer's weights.

Finally:

b1 -= learning_rate * db1

updates the hidden-layer biases.

These updates are what actually allow the network to learn.

25. The Complete NumPy Neural Network

Now let's put everything together.

import numpy as np

# 1. Training data

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

# 2. Initialize parameters

np.random.seed(42)

W1 = np.random.randn(2, 4)
b1 = np.zeros((1, 4))

W2 = np.random.randn(4, 1)
b2 = np.zeros((1, 1))

learning_rate = 0.1

# 3. Activation functions

def sigmoid(x):
    return 1 / (1 + np.exp(-x))

# 4. Training

for epoch in range(10000):

    # Forward propagation

    z1 = X @ W1 + b1
    a1 = np.tanh(z1)

    z2 = a1 @ W2 + b2
    a2 = sigmoid(z2)

    # Calculate loss

    loss = -np.mean(
        y * np.log(a2 + 1e-8) +
        (1 - y) * np.log(1 - a2 + 1e-8)
    )

    # Backpropagation

    dz2 = a2 - y

    dW2 = (a1.T @ dz2) / len(X)
    db2 = np.mean(dz2, axis=0, keepdims=True)

    da1 = dz2 @ W2.T

    dz1 = da1 * (1 - a1**2)

    dW1 = (X.T @ dz1) / len(X)
    db1 = np.mean(dz1, axis=0, keepdims=True)

    # Update parameters

    W2 -= learning_rate * dW2
    b2 -= learning_rate * db2

    W1 -= learning_rate * dW1
    b1 -= learning_rate * db1

    # Display progress

    if epoch % 1000 == 0:
        print(f"Epoch {epoch}, Loss: {loss:.4f}")

Let's go through the program from top to bottom.

Line-by-Line Explanation of the Full Code

Importing NumPy:

import numpy as np

We import NumPy because our network will work with arrays and matrix operations.

Creating the inputs

X = np.array([
    [0, 0],
    [0, 1],
    [1, 0],
    [1, 1]
])

Each row is one XOR example.

There are four examples and two input values per example.

So the shape of X is:

4 × 2

Creating the answers

y = np.array([
    [0],
    [1],
    [1],
    [0]
])

There are four correct answers, one for each row in X.

Making random initialization reproducible

np.random.seed(42)

This makes NumPy generate the same starting random values each time.

The number 42 isn't special. You could use another number.

Creating the first weight matrix

W1 = np.random.randn(2, 4)

This creates a matrix containing random numbers.

Its shape is 2*4

There are two inputs and four hidden neurons.

Creating the first biases

b1 = np.zeros((1, 4))

This creates four zeros:

[0, 0, 0, 0]

There is one bias for every hidden neuron.

Creating the second weight matrix

W2 = np.random.randn(4, 1)

There are four hidden neurons and one output neuron.

Therefore:

4 × 1

weights are needed.

Creating the output bias

b2 = np.zeros((1, 1))

The output layer has one neuron, so it needs one bias.

Setting the learning rate

learning_rate = 0.1

This controls how strongly the gradients affect each update.

Creating sigmoid

def sigmoid(x):
    return 1 / (1 + np.exp(-x))

This converts the output into a value between 0 and 1.

Starting the Training Loop

for epoch in range(10000):

This tells Python to repeat the training process 10,000 times.

Each repetition is an epoch, which is one complete pass of the entire training dataset through a neural network

Calculating the hidden layer

z1 = X @ W1 + b1

This performs the weighted-sum calculation for all four hidden neurons and all four training examples.

Applying tanh

a1 = np.tanh(z1)

This applies the nonlinear activation function to the hidden layer.

Calculating the output layer

z2 = a1 @ W2 + b2

This takes the hidden layer's values and calculates the output neuron's weighted sum.

Applying sigmoid

a2 = sigmoid(z2)

This turns the output into probabilities between 0 and 1.

Calculating the loss

loss = -np.mean(
    y * np.log(a2 + 1e-8) +
    (1 - y) * np.log(1 - a2 + 1e-8)
)

This measures how different the predictions are from the correct answers.

A lower value generally means the predictions are better.

Calculating the output gradient

dz2 = a2 - y

This calculates the gradient needed to update the output layer.

Updating the second-layer weight gradients

dW2 = (a1.T @ dz2) / len(X)

This determines how each weight connecting the hidden layer to the output layer contributed to the loss.

Updating the output bias gradient

db2 = np.mean(dz2, axis=0, keepdims=True)

This calculates the average gradient for the output bias.

Moving backward toward the hidden layer

da1 = dz2 @ W2.T

This passes the gradient information backward through the output layer.

Applying the tanh derivative

dz1 = da1 * (1 - a1**2)

This accounts for the effect of the tanh activation function.

Calculating the first-layer gradients

dW1 = (X.T @ dz1) / len(X)

This determines how the input-to-hidden weights contributed to the loss.

Then:

db1 = np.mean(dz1, axis=0, keepdims=True)

calculates the gradients for the hidden-layer biases.

Updating the parameters

W2 -= learning_rate * dW2
b2 -= learning_rate * db2

W1 -= learning_rate * dW1
b1 -= learning_rate * db1

These four lines are where the network changes what it has learned.

The gradients tell us which direction to move, while the learning rate determines how large the movement should be.

Printing the loss

if epoch % 1000 == 0:
    print(f"Epoch {epoch}, Loss: {loss:.4f}")

The % operator gives us the remainder after division.

So:

epoch % 1000 == 0

is true every 1,000 epochs.

That means we don't print something 10,000 times. Instead, we get occasional updates such as:

Epoch 0, Loss: ...
Epoch 1000, Loss: ...
Epoch 2000, Loss: ...
...

If training is working well, the loss should generally decrease.

26. Testing the Network

After training, we can use the network to make predictions.

z1 = X @ W1 + b1
a1 = np.tanh(z1)

z2 = a1 @ W2 + b2
predictions = sigmoid(z2)

print(predictions)

The network should produce values close to:

[[0],
 [1],
 [1],
 [0]]

The actual values probably won't be exactly 0 and 1.

You might get something more like:

[[0.01],
 [0.98],
 [0.99],
 [0.02]]

That's fine.

The network is producing probabilities.

We can convert those probabilities into classes using a threshold:

classes = (predictions >= 0.5).astype(int)

print(classes)

The result should be:

[[0],
 [1],
 [1],
 [0]]

Our network has learned the XOR pattern.

27. Why Did We Need a Hidden Layer?

You might wonder why we couldn't just connect the two inputs directly to the output.

The reason is that XOR isn't something a single linear layer can represent.

The hidden layer gives the network additional transformations that allow it to learn the more complicated relationship.

This is one of the most important ideas behind neural networks: a network doesn't necessarily learn one giant rule. Instead, different layers can transform information step by step.

For an image recognition system, you can imagine a simplified process like:

Real neural networks don't literally create neat layers called "edges," "shapes," and "objects." This is just an intuition for how increasingly complex representations can emerge through multiple layers.

28. What Happens in a Larger Neural Network?

The network we built is tiny. Modern neural networks can have millions, billions, or even more parameters.

A simplified network might look like:

Each connection can have its own weight.

The more neurons and connections a network has, the more parameters it may need to learn.

Large models therefore require significant amounts of computing power and memory.

But remember the basic process:

Input
 ↓
Calculations
 ↓
Prediction
 ↓
Loss
 ↓
Gradients
 ↓
Parameter Updates

The size of the network changes dramatically, but the basic training idea remains.

29. Do You Have to Build Neural Networks From Scratch?

No. Building a neural network from scratch is useful for learning because it forces you to understand what's happening underneath the libraries.

But you normally wouldn't manually calculate every gradient when building a real machine learning application.

That's where machine learning frameworks come in. Some commonly used Python libraries include:

• NumPy

• PyTorch

• TensorFlow

• Keras

• scikit-learn

For deep learning, PyTorch is one of the most commonly used frameworks. It can automatically calculate gradients and handle many of the mathematical operations involved in training.

30. Building the Same Network With PyTorch

Let's see how much shorter the network becomes with PyTorch.

First, install it:

pip install torch

Then import it:

import torch
import torch.nn as nn

Now create the model:

model = nn.Sequential(
    nn.Linear(2, 4),
    nn.Tanh(),
    nn.Linear(4, 1),
    nn.Sigmoid()
)

Let's break that down.

nn.Linear(2, 4)

creates a layer that takes two inputs and produces four outputs.

That's our hidden layer.

Next:

nn.Tanh()

applies the tanh activation function.

Then:

nn.Linear(4, 1)

connects the four hidden neurons to one output neuron.

Finally:

nn.Sigmoid()

converts the output into a value between 0 and 1.

So the architecture is:

2 inputs
   ↓
4 hidden neurons
   ↓
Tanh
   ↓
1 output neuron
   ↓
Sigmoid

Notice how much shorter this is than our NumPy implementation.

That's because PyTorch handles many of the calculations for us.

31. Training the Network With PyTorch

First, create the training data:

X = torch.tensor([
    [0., 0.],
    [0., 1.],
    [1., 0.],
    [1., 1.]
])

y = torch.tensor([
    [0.],
    [1.],
    [1.],
    [0.]
])

The decimal points are important because neural networks normally work with floating-point numbers.

Now create the model:

model = nn.Sequential(
    nn.Linear(2, 4),
    nn.Tanh(),
    nn.Linear(4, 1),
    nn.Sigmoid()
)

Next, choose our loss function:

loss_function = nn.BCELoss()

BCELoss calculates binary cross-entropy loss.

Now create an optimizer:

optimizer = torch.optim.Adam(
    model.parameters(),
    lr=0.01
)

Adam is an optimization algorithm that updates the model's parameters during training.

model.parameters() tells the optimizer which values it should update.

lr=0.01 sets the learning rate.

Now we can train:

for epoch in range(5000):

    predictions = model(X)

    loss = loss_function(predictions, y)

    optimizer.zero_grad()

    loss.backward()

    optimizer.step()

    if epoch % 500 == 0:
        print(
            f"Epoch {epoch}, Loss: {loss.item():.4f}"
        )

Let's look at the important parts.

First:

predictions = model(X)

This sends the training data through the network.

Then:

loss = loss_function(predictions, y)

compares the predictions with the correct answers.

Next:

optimizer.zero_grad()

clears gradients from the previous training step.

Then:

loss.backward()

calculates the gradients automatically using backpropagation.

Finally:

optimizer.step()

uses those gradients to update the model's parameters.

That's the same basic learning process we implemented manually with NumPy. The difference is that PyTorch takes care of many of the calculations.

32. NumPy vs. PyTorch

So why did we build the network twice? Well, because the two versions teach different things.

With NumPy, we manually handled weights, biases, forward propagation,
loss, gradients, backpropagation, and parameter updates. That makes the mechanics easier to see.

With PyTorch, we can write the same general idea in much less code because the framework handles many of those calculations.

You can think of it like this:

Learning how the NumPy version works makes the PyTorch version much less mysterious.

33. What Is Deep Learning?

You may have heard the term deep learning. Deep learning is a part of machine learning that uses neural networks with multiple layers.

For example:

Input
  ↓
Layer 1
  ↓
Layer 2
  ↓
Layer 3
  ↓
Layer 4
  ↓
Output

The word "deep" refers to the depth of the network, or the number of layers involved.

There isn't a magical point where a neural network suddenly becomes intelligent. Adding layers simply gives the model more opportunities to transform the input into useful representations.

34. Where Are Neural Networks Used?

Neural networks are used in many different areas. Here are a few examples...

Computer Vision

Neural networks can process images.

For example:

Image
  ↓
Neural Network
  ↓
Prediction

They can be used for tasks such as image classification and object detection.

Natural Language Processing

Neural networks can also process text.

For example:

Text
  ↓
Neural Network
  ↓
Prediction

Modern language models use neural networks to process and generate text.

Speech Recognition

Neural networks can process audio and help convert spoken language into text.

Audio
  ↓
Neural Network
  ↓
Words

Recommendation Systems

Neural networks can learn patterns from user behavior and help predict which content or products might be useful to someone.

Generative AI

Large neural networks can also be used to generate text, images, audio, code, video, and much more.

These systems are much more complicated than the small XOR network we built, but they still rely on the same general idea of learning parameters from data.

35. The Whole Process in One Picture

At this point, we've covered a lot.

Here's the entire training process:

Data
   ↓
Neural Network
   ↓
Prediction
   ↓
Loss
  ↓
Backpropagation
  ↓
Update Parameters
  ↓
Repeat

Once training is finished, we use the learned parameters to make predictions on new data:

New Data
   ↓
Trained Neural Network
   ↓
Prediction

That's the basic idea behind neural network training.

36. The Most Important Ideas to Remember

If you don't remember every equation from this tutorial, that's okay.

Start with these concepts.

Inputs

The numbers we give to the network.

x₁, x₂, x₃...

Weights

Numbers that determine how strongly inputs affect neurons.

w₁, w₂, w₃...

Biases

Additional values that give neurons more flexibility.

b

Activation Functions

Functions that transform neuron outputs and allow networks to learn nonlinear patterns.

Examples include:

ReLU
Tanh
Sigmoid

Forward Propagation

Sending data from the input toward the output.

Input → Hidden Layers → Output

Loss

A measurement of how different the prediction is from the correct answer.

Backpropagation

Calculating gradients by working backward through the network.

Gradient Descent

Using those gradients to update the network's parameters.

And the entire learning process can be summarized as:

Predict
   ↓
Measure Error
   ↓
Calculate Gradients
   ↓
Update Parameters
   ↓
Repeat

37. What Should You Learn Next?

If you want to continue learning neural networks with Python, you don't need to jump directly into complicated research papers.

A useful learning path is:

Python
  ↓
NumPy
  ↓
Basic Linear Algebra
  ↓
Probability & Statistics
  ↓
Machine Learning Basics
  ↓
Neural Networks
  ↓
PyTorch
  ↓
Deep Learning
  ↓
Computer Vision / NLP / Generative AI

You can also learn by building small projects.

For example:

1. XOR classifier

2. House price predictor

3. Handwritten digit classifier

4. Simple image classifier

5. Spam message classifier

6. Neural network that learns a mathematical function

The projects don't need to be huge. A small project that you completely understand is often more useful than a large project where you copied code without understanding it.

Final Takeaway

Neural networks can look intimidating because the systems used in modern AI can contain enormous numbers of parameters.

But the basic idea is much smaller.

A neural network takes numbers as input, combines them using weights and biases, applies mathematical functions, produces a prediction, measures how wrong that prediction was, and then adjusts its parameters.

The cycle looks like this:

Input
  ↓
Weighted Calculations
  ↓
Activation Functions
  ↓
Prediction
  ↓
Loss
  ↓
Gradients
  ↓
Parameter Updates
  ↓
Repeat

That's the foundation.

The XOR network we built in this tutorial is tiny compared with the neural networks used in modern AI. But the ideas you just learned (parameters, layers, activation functions, forward propagation, loss, backpropagation, gradients, and optimization) are fundamental ideas that appear again and again in deep learning.

The next time you hear that an AI model has millions or billions of parameters, it might still sound overwhelming.

But underneath all that scale, the basic learning loop is still familiar:

1. Make a prediction.

2. Measure the error.

3. Figure out how to improve.

4. Update the parameters.

5. Try again.

And that's the core idea behind a neural network.

Happy coding and keep learning!

When I first started looking into how they worked, I assumed there had to be a huge amount of complicated code behind all of it.

But the basic idea is actually pretty simple.

At its core, a Discord bot is just a Python program that connects to Discord, waits for something to happen, and then decides how to respond. Once you understand that basic idea, you can start adding features one at a time and turn a simple bot into something much more interesting.

In this tutorial, we'll start with a very small bot and gradually build it into something more capable. Along the way, you'll learn about Discord commands, events, asynchronous Python, user state, environment variables, and basic deployment.

One quick disclaimer before we start: the mental-wellness feature that we'll be integrating in this bot in this project is not therapy, and the bot is not a therapist or medical professional. It should only provide general supportive suggestions and encourage users to reach out to a trusted person when appropriate.

With that out of the way, let's get coding!

What We'll Cover:

• What We're Building

• What You Need

• Create the Discord Bot

• Give the Bot Permission to Read Messages

• Create the Project

• Create a Virtual Environment

• Install discord.py

• Create Your First Bot

  • Importing Our Libraries

  • Loading the Token

  • Understanding Intents

  • What Isctx?

  • Why Does Everything Sayasyncandawait?

  • Run the Bot

• Build the Storytelling System

  • Let's Make the Story Remember the User

  • Add a Story Choice

  • Add a Casual Chat Command

  • Add a Mental-Wellness Support Feature

  • Add a Help Command

  • Improve Error Handling

• Put Everything Together

• Our Bot Doesn't Actually Remember Anything

  • Create the Database

  • Save a User's Story

  • Get the Story Back

  • Put It Into a Command

• Adding Real AI Chat

  • Install the Hugging Face Library

  • Create the Hugging Face Client

  • Connect the AI Model to the Bot

  • Handle AI Errors

• How Do We Keep the Bot Online?

  • Option 1: Run It on Your Computer

  • Option 2: Host It on a Server

• What "Forever" Actually Means

• Don't Try to "Keep It Awake" With Random Tricks

• Additional Features and Where to Go Next

• Test Everything Locally First

• Deploying the Bot

  • The Start Command

• Remember: Keep Your Secrets Secret

• What You Learned

• Final Thoughts

What We're Building

Our finished bot will have several commands:

!hello
!story
!chat hello!
!support I'm having a stressful day
!help

For example:

User:
!story

Bot:
You wake up inside an abandoned library.

There are three doors in front of you:

1. A red wooden door
2. A metal door covered in strange symbols
3. A staircase leading underground

Which one do you choose?

The user can then continue the story.

For chat:

User:
!chat What's a good way to learn Python?

Bot:
Try building small projects instead of only reading tutorials.
A Discord bot is actually a pretty fun project to start with.

And for mental-wellness support:

User:
!support I'm really stressed about school.

Bot:
That sounds like a lot to deal with. You could try breaking
the work into one small task at a time and taking a short
break between tasks.

I'm a bot, not a therapist, so if you need personal support,
consider talking with someone you trust.

The goal isn't to make a magical robot therapist. It's to build a useful bot while learning how Discord APIs, Python functions, events, asynchronous programming, and basic conversational logic fit together.

What You Need

You only need a few things:

• Python (version 3.8+ is recommended)

• A Discord account

• A Discord server where you have permission to add a bot

• A code editor (I personally prefer VS Code or PyCharm)

• The discord.py library

We'll also use Python's built-in os module for reading environment variables.

If you don't already have Python installed, install a current supported version of Python from the official Python website.

Then check that Python works:

python --version

You should see something similar to:

Python 3.x.x

Create the Discord Bot

Before Python can control Discord, we need to create a Discord application.

Go to the Discord Developer Portal: https://discord.com/developers/applications

This is what the page will look like, you might need to login with your discord email/username and password before you start.

Click on the "New Application" button on the top right and give your bot a name. For this tutorial, let's call ours StoryBot.

The application is basically the home for your bot.

Discord's developer platform provides the tools needed to create and configure applications and bots.

Once you've created the application, open its Bot section and create the bot user. You can add your own icon picture and your own banner if you want to.

You will then go to the Token section and click on "Reset Token" to generate your token. Treat that token like a password. Do NOT put it directly into your Python source code.

Never do this:

bot.run("my-secret-token")

And definitely don't upload a token to GitHub or commit it to source control. Instead, we'll store it in an environment variable, which we'll talk about later.

Give the Bot Permission to Read Messages

Our bot needs to see the messages that contain commands.

Discord uses something called Gateway Intents to control which types of events a bot receives. The discord.py documentation explains that intents must be enabled both in your code and, for privileged intents, in the Discord Developer Portal.

In the Developer Portal, find:

Bot
→ Privileged Gateway Intents

Enable:

Message Content Intent

It should look somewhat like this:

We'll also enable it in Python, which we will talk about later in this article.

Create the Project

Create a folder:

discord-story-bot/

Inside it, we'll eventually have:

discord-story-bot/
│
├── bot.py
├── requirements.txt
└── .env

The three important files are:

• bot.py: our Python program

• requirements.txt: text file that contains the name of the packages our bot needs

• .env: our secret token during local development

Create a Virtual Environment

Open your terminal inside the project folder.

Run:

python -m venv venv

Then activate it.

On Windows:

venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

A virtual environment gives this project its own little Python bubble.

That means packages installed for this bot won't randomly interfere with packages used by another project.

Install discord.py

Now install the Discord library:

pip install -U discord.py

The official discord.py documentation uses this installation approach for setting up the library.

We'll also install python-dotenv, which makes reading our local .env file easier:

pip install python-dotenv

Then save the dependencies:

pip freeze > requirements.txt

Your requirements.txt should contain the packages needed by the project.

Create Your First Bot

Let's start small.

Open bot.py:

import os

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


bot.run(TOKEN)

That is already a functional Discord bot.

Let's break it apart piece by piece.

Importing Our Libraries

First:

import os

os lets Python communicate with parts of the operating system.

We'll use it to read environment variables.

Next:

import discord

This imports discord.py.

Then:

from discord.ext import commands

The commands extension makes creating commands much easier.

Instead of manually checking every message for something like !hello, we can write:

@bot.command()
async def hello(ctx):
    await ctx.send("Hello!")

The discord.py command system is built around Python functions decorated as commands.

Finally:

from dotenv import load_dotenv

This lets us load values from our .env file.

Loading the Token

Our bot needs a token to connect our Python program to Discord. Think of the token as a password that allows our program to authenticate as the bot.

We don't want to put this secret directly into our Python code. Instead, we'll store it in an environment variable.

First, install python-dotenv:

pip install python-dotenv

This package lets Python read values from a .env file.

Now create a new file called .env in the same folder as bot.py.

Inside .env, add:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE

Replace YOUR_BOT_TOKEN_HERE with the token you copied from the Discord Developer Portal.

Your file should look something like this:

DISCORD_TOKEN=your_actual_token_here

Don't share this token with anyone or upload your .env file to GitHub. Your bot token should be treated like a password.

To make sure Git doesn't accidentally include the .env file in a repository, create a file called .gitignore in your project folder and add:

.env
venv/
__pycache__/

Now let's load the token in Python.

At the top of bot.py, add:

import os
from dotenv import load_dotenv

Then add:

load_dotenv()

This tells Python to look for the .env file and load the variables inside it.

Now we can get our Discord token:

TOKEN = os.getenv("DISCORD_TOKEN")

os.getenv() looks for the environment variable named "DISCORD_TOKEN" and gives us its value.

We can also check that the token was actually found:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

If Python can't find the token, the program stops and gives us a clear error message instead of failing later in a confusing way.

Understanding Intents

Remember how we talked about enabling message content readability in python? We are going to do that now.

Add:

intents = discord.Intents.default()
intents.message_content = True

The first line creates a set of Discord's default intents.

The second line tells Discord that our bot needs access to message content.

Now we need to give these intents to our bot when we create it:

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

The command_prefix="!" means our bot will recognize commands that begin with !.

For example:

!hello

The intents=intents part gives our bot the permissions we configured above.

There are two steps here because Discord needs to know that our bot is allowed to receive message content, while our Python program also needs to tell Discord that it wants to receive it.

Our basic setup should now look like this:

import os
import discord

from dotenv import load_dotenv
from discord.ext import commands

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

Now our bot has its token safely loaded and discord.py knows which intents to request when it connects to Discord.

What Is ctx?

This part can look weird when you're learning Discord bots:

async def hello(ctx):

What is ctx? ctx stands for context. It contains information about the command that was used.

For example, it can tell us:

• Who ran the command

• Which server it came from

• Which channel it came from

• What message triggered it

Then:

await ctx.send("Hello!")

means:

"Send this message back to the place where the command was used."

Why Does Everything Say async and await?

You might notice:

async def hello(ctx):

and:

await ctx.send(...)

Discord bots spend a lot of time waiting.

They wait for:

• Messages

• Discord responses

• API requests

• Timers

• Other events

Python's asynchronous programming features allow the bot to wait for these operations without freezing everything else.

You don't need to become an async-programming expert before building your first bot.

For now, think of await as:

"Pause this task until this operation finishes, while letting the bot handle other things."

Run the Bot

Start it with:

python bot.py

If everything works, your terminal should print something similar to:

Logged in as StoryBot

Now go to your Discord server and type !hello. Your bot should respond.

Congratulations! You've officially made a Discord bot.

Now let's make it interesting.

Build the Storytelling System

First, we're going to create an interactive storytelling command.

At the top of bot.py, add:

import random

Then create some story ingredients:

story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]

Now create the command:

@bot.command()
async def story(ctx):
    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    story_text = (
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

    await ctx.send(story_text)

Now !story might produce:

You wake up in a futuristic city.

Next to you is an ancient notebook.

A hidden door opens nearby.

What do you do?

Run it again and you might get something completely different.

That's because of:

random.choice(...)

Python randomly picks one item from each list.

It's a simple technique, but suddenly your bot can generate hundreds of different combinations.

Let's Make the Story Remember the User

Random stories are fun, but interactive stories are much better when the bot remembers what happened.

We can create a dictionary:

user_stories = {}

The dictionary will store story information for each user.

For example:

user ID → current story

Now let's modify the story command:

@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

Now each user can have their own active story.

Add a Story Choice

Let's give users choices.

@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send("You don't have an active story. Try `!story` first.")
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)

Now users can type:

!choose left

or:

!choose right

Notice this:

async def choose(ctx, choice: str):

The choice parameter receives the text after the command.

So:

!choose left

becomes approximately:

choice = "left"

This is one of the reasons command frameworks are so convenient. A command framework is a set of tools that makes it easier to create and manage commands in a program. In our case, discord.py provides the command framework that lets us turn Python functions into Discord commands using decorators like @bot.command().

Instead of manually checking every message to figure out whether someone typed !choose, discord.py handles that work for us. It recognizes the command, takes the user's arguments, and passes them to our function.

So when someone types:

!choose left

discord.py knows that choose is the command, "left" is the argument, and that it should call our choose() function with that information.

Add a Casual Chat Command

Now let's make the bot capable of basic conversation.

We could connect it to a large language model API, but you don't actually need AI to learn how a chat command works. We'll start with a simple keyword-based response system.

First, we'll create a dictionary containing some keywords and possible responses:

chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],
    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],
    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}

Think of `chat_responses` as a small collection of things our bot knows how to talk about. Each key, such as `"python"` or `"discord"`, represents a keyword the bot can look for. The value associated with each key is a list of possible responses.

We use a list instead of a single response so the bot doesn't give exactly the same answer every time. Later, we'll randomly choose one of these responses.

Now let's create the actual `!chat` command:

```python
@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )

There are a few things happening here, so let's break it down.

First, this part:

@bot.command()
async def chat(ctx, *, message: str):

turns the chat() function into a Discord command. The * is important because it tells discord.py to treat everything after the command as one argument.

For example, if someone types:

!chat I want to learn Python

the entire phrase after !chat becomes the value of message:

message = "I want to learn Python"

Next, we have:

text = message.lower()

This converts the message to lowercase. That means Python, python, and PYTHON will all become python. Without this, our keyword check could miss a match simply because the user capitalized a word differently.

Now we get to the loop:

for keyword, responses in chat_responses.items():

.items() lets us go through both the keyword and its corresponding list of responses. During each loop, keyword contains something like "python", while responses contains the list of responses associated with it.

Then we check:

if keyword in text:

This asks whether the current keyword appears anywhere in the user's message.

If the user writes:

!chat I want to learn Python

the lowercase version becomes:

i want to learn python

Since "python" appears inside that text, the condition is true.

The bot can then choose a random response:

await ctx.send(random.choice(responses))

random.choice() picks one item from the response list, while ctx.send() sends that response back to the Discord channel.

Finally, we have:

return

This stops the function after a matching keyword is found. Without it, the loop would continue checking the other keywords even after the bot had already responded.

But what happens if none of the keywords match?

That's what this part handles:

await ctx.send(
    "I'm still learning how to respond to that. "
    "Try talking to me about Python or Discord!"
)

If the loop finishes without finding a keyword, the bot sends this fallback message instead.

For example:

!chat I like pizza

doesn't contain "hello", "python", or "discord", so the bot doesn't have a specific response to use.

This gives us a simple way for the bot to have conversations without needing an AI model.

Add a Mental-Wellness Support Feature

Now for the feature that needs a little more care.

Instead of calling this a "therapy command" internally, we'll call it:

!support

Quick additional disclaimer before we start...this is just a fun wellness script, not a real therapist!

Create:

support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}

Now create the command:

@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )

Now someone can type:

!support I'm stressed about school

The bot sees the word:

school

and chooses one of the school-related responses.

This is deliberately simple.

For a real public bot, you'd want much more careful safety handling, testing, moderation, privacy protection, and escalation logic before allowing users to rely on it for sensitive situations.

Add a Help Command

A good bot should explain itself.

@bot.command()
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )

There's one small issue.

Discord's default help command is already called help.

So instead of:

async def help(ctx):

we've named ours:

commands_help

If you want the command itself to be called !help, you can write:

@bot.command(name="help")
async def commands_help(ctx):
    ...

That tells Discord:

Use !help for this function even though the Python function has another name.

Improve Error Handling

Bots shouldn't crash just because someone enters an invalid command.

Add:

@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")

Now if someone types:

!chat

without giving the bot a message, it can respond with a useful explanation instead of dumping a confusing error into the conversation.

Put Everything Together

At this point, your bot.py can look like this:

import os
import random

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")


intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]


user_stories = {}


chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],

    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],

    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}


support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )


@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send(
            "You don't have an active story. Try `!story` first."
        )
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)


@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )


@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )


@bot.command(name="help")
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )


@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")


bot.run(TOKEN)

This is enough to create a surprisingly capable beginner Discord project.

But there's an important limitation.

Our Bot Doesn't Actually Remember Anything

There's one small problem with our bot so far: it doesn't actually remember anything after it shuts down.

Right now, we're storing our story information in a Python dictionary:

user_stories = {}

This works while the bot is running. But if you stop the program and start it again, the dictionary starts empty.

To fix this, we need somewhere to permanently store our data. That's where a database comes in.

For this project, we'll use SQLite. SQLite is a lightweight database that stores information in a file on your computer. Python already includes SQLite through the built-in sqlite3 module, so we don't need to install anything extra.

Create the Database

First, add this import near the top of bot.py:

import sqlite3

Then create a connection to a database file:

db = sqlite3.connect("bot.db")
cursor = db.cursor()

The first line creates a database file called bot.db if one doesn't already exist. If the file already exists, SQLite simply opens it.

The second line creates a cursor. You can think of the cursor as the part of our Python program that lets us send instructions to the database.

Now we need to create a table where we can store our users' story information:

cursor.execute("""
    CREATE TABLE IF NOT EXISTS user_stories (
        user_id INTEGER PRIMARY KEY,
        location TEXT,
        item TEXT,
        event TEXT
    )
""")

db.commit()

Let's break this down.

cursor.execute() tells SQLite to run the SQL command inside the parentheses.

The SQL command starts with:

CREATE TABLE IF NOT EXISTS user_stories

This tells SQLite to create a table called user_stories, but only if that table doesn't already exist.

Inside the parentheses, we define the information that each row can contain:

user_id INTEGER PRIMARY KEY,
location TEXT,
item TEXT,
event TEXT

user_id stores the Discord user's ID. We use it as the PRIMARY KEY, which means each user gets their own unique row.

location, item, and event are all pieces of information about the user's current story.

Finally:

db.commit()

saves the changes to the database.

At this point, your project folder should contain a new file called:

bot.db

You don't need to open or edit this file manually. SQLite will manage it for us.

Save a User's Story

Now let's actually put information into our database.

Suppose we have these variables:

user_id = ctx.author.id
location = "an abandoned castle"
item = "a mysterious key"
event = "a locked door"

We can save them using:

cursor.execute(
    """
    INSERT OR REPLACE INTO user_stories
    (user_id, location, item, event)
    VALUES (?, ?, ?, ?)
    """,
    (user_id, location, item, event)
)

db.commit()

The SQL statement tells SQLite to insert the information into the user_stories table.

The ? symbols are placeholders for the actual values. The values are provided separately here:

(user_id, location, item, event)

This is safer than manually inserting values directly into the SQL string.

INSERT OR REPLACE also means that if this user already has a saved story, their old story information can be replaced with the new information.

Get the Story Back

Saving information is only half of the job. We also need to be able to retrieve it.

We can search the database for a user's story like this:

cursor.execute(
    """
    SELECT location, item, event
    FROM user_stories
    WHERE user_id = ?
    """,
    (user_id,)
)

story = cursor.fetchone()

This time, we're using SELECT to ask SQLite for information.

The WHERE part is important:

WHERE user_id = ?

It tells SQLite to find the row belonging to this specific Discord user.

Then:

story = cursor.fetchone()

gets the first matching result.

If the user has a saved story, story will contain their information. If they don't, story will be None.

We can check for that:

if story:
    location, item, event = story

    await ctx.send(
        f"You're currently in {location}. "
        f"You have {item}, and you're facing {event}."
    )
else:
    await ctx.send("I don't have a saved story for you yet!")

Now the bot can retrieve information that was saved earlier, even after the Python program has been restarted.

Put It Into a Command

We can turn this into a simple command that lets users check their saved story:

@bot.command()
async def status(ctx):
    user_id = ctx.author.id

    cursor.execute(
        """
        SELECT location, item, event
        FROM user_stories
        WHERE user_id = ?
        """,
        (user_id,)
    )

    story = cursor.fetchone()

    if story:
        location, item, event = story

        await ctx.send(
            f"You're currently in {location}. "
            f"You have {item}, and you're facing {event}."
        )
    else:
        await ctx.send(
            "You don't have a saved story yet. "
            "Start one with `!story`!"
        )

Now a user can type:

!status

and the bot can look up their story from the database.

This is a big improvement over our original dictionary. A dictionary only remembers information while the Python program is running. SQLite lets us save that information so it can still be there when the bot starts again.

For a larger bot, you could eventually store things like user preferences, story progress, inventory, conversation history, or other data. But for now, this simple database is enough to give our bot some real memory.

Adding Real AI Chat

Before we connect our bot to an AI model, let's quickly talk about Hugging Face.

If you've never used it before, Hugging Face is a platform where developers can find, share, and use machine learning models and datasets. Think of it as a huge community and library for AI tools.

Hugging Face also provides tools that let Python programs communicate with these models without having to build and train an AI model from scratch.

For our bot, we'll use Hugging Face's Inference Providers to send a user's message to a supported language model and receive its response.

We won't be training an AI model ourselves. Instead, we'll use an existing model and connect it to our Discord bot through Python.

Now that we know what Hugging Face is, let's connect it to our bot.

Install the Hugging Face Library

First, install huggingface_hub:

pip install -U huggingface_hub

We already installed python-dotenv, so we can use the same .env file from earlier to keep our Hugging Face token out of the source code.

Add your Hugging Face token to .env:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE
HF_TOKEN=YOUR_HUGGING_FACE_TOKEN_HERE

Replace YOUR_HUGGING_FACE_TOKEN_HERE with your actual Hugging Face access token.

Just like your Discord bot token, don't share this token or upload it to GitHub.

Create the Hugging Face Client

Now add this import near the top of bot.py:

from huggingface_hub import InferenceClient

Then load the token:

HF_TOKEN = os.getenv("HF_TOKEN")

if not HF_TOKEN:
    raise RuntimeError("HF_TOKEN is not set.")

The first line gets the token from our environment variables. The if statement checks whether the token actually exists. If it doesn't, Python stops and gives us a useful error instead of letting the program fail later in a confusing way.

Now create the Hugging Face client:

client = InferenceClient(
    api_key=HF_TOKEN
)

The InferenceClient is what our Python program will use to communicate with Hugging Face's inference service.

Connect the AI Model to the Bot

Now we can replace our previous keyword-based !chat command with one that sends the user's message to a language model.

@bot.command()
async def chat(ctx, *, message: str):
    try:
        response = client.chat_completion(
            model="YOUR_SUPPORTED_MODEL_ID",
            messages=[
                {
                    "role": "system",
                    "content": (
                        "You are a friendly Discord bot. "
                        "Keep responses helpful, concise, and conversational."
                    )
                },
                {
                    "role": "user",
                    "content": message
                }
            ],
            max_tokens=200
        )

        answer = response.choices[0].message.content

        await ctx.send(answer)

    except Exception as error:
        print(f"AI error: {error}")
        await ctx.send(
            "I couldn't generate a response right now. "
            "Please try again later."
        )

There's quite a bit happening here, so let's walk through it.

We start with the same command structure we've already used:

@bot.command()
async def chat(ctx, *, message: str):

This creates our !chat command and stores everything the user types after it in message.

For example:

!chat What is Python?

gives us:

message = "What is Python?"

Next, we use:

try:

This tells Python that we're about to run code that could potentially fail. Since we're communicating with an external service, things like an unavailable model, an invalid token, or a temporary connection problem can happen.

Now we call:

response = client.chat_completion(

This sends a chat-completion request to the model through Hugging Face. The messages parameter contains the conversation we want the model to respond to.

The first message has the role "system":

{
    "role": "system",
    "content": (
        "You are a friendly Discord bot. "
        "Keep responses helpful, concise, and conversational."
    )
}

The system message gives the model instructions about how it should respond.

Then we provide the user's actual message:

{
    "role": "user",
    "content": message
}

If the user typed:

!chat What is Python?

then message contains:

What is Python?

So the model receives that as the user's input.

We also have:

max_tokens=200

This limits how much text the model can generate for one response. Keeping responses relatively short works well for Discord because huge blocks of text aren't always very pleasant to read in a chat channel.

You also need to replace:

model="YOUR_SUPPORTED_MODEL_ID"

with the ID of a model currently available through the Hugging Face Inference Providers you are using. Hugging Face's documentation shows that InferenceClient can use a model ID hosted on the Hugging Face Hub for chat completion.

Once the request is complete, we need to get the actual text from the response:

answer = response.choices[0].message.content

The response contains information about the model's output. choices[0] gets the first generated response, and .message.content gives us the actual text.

Then we send it to Discord:

await ctx.send(answer)

So the whole process looks like this:

User types !chat
        ↓
Discord sends the command to our bot
        ↓
Python gets the user's message
        ↓
Hugging Face receives the message
        ↓
The AI model generates a response
        ↓
Python gets the generated text
        ↓
The bot sends it back to Discord

Handle AI Errors

The last part of our command is:

except Exception as error:
    print(f"AI error: {error}")
    await ctx.send(
        "I couldn't generate a response right now. "
        "Please try again later."
    )

If something goes wrong inside the try block, Python jumps to the except block instead of crashing the entire bot.

The error is printed in the terminal so you can investigate what happened:

print(f"AI error: {error}")

Meanwhile, the Discord user gets a simple message:

I couldn't generate a response right now. Please try again later.

This is much better than letting an API error take down the whole bot.

At this point, you have a real AI-powered !chat command. You can type something like:

!chat Tell me an interesting fact about space.

and the model can generate a response instead of choosing from a small list of pre-written messages.

One thing to remember is that this bot is sending user messages to an external AI service. Don't automatically send private or sensitive conversations to an AI provider. If you make this bot available to other people, be clear about what information it processes and avoid storing or sending more data than the bot actually needs.

You can also combine this AI system with the SQLite database from earlier. For example, you could save a limited amount of conversation history and send relevant previous messages along with a new message. That would allow the bot to keep some context between messages instead of treating every message as a completely new conversation.

How Do We Keep the Bot Online?

Here's where the phrase "online forever" needs a little clarification.

There are two different situations.

Option 1: Run It on Your Computer

When you run:

python bot.py

the bot stays online while that program is running.

Close the terminal?

Bot goes offline.

Turn off the computer?

Bot goes offline.

Lose internet?

Bot goes offline.

This is perfect for development but it's not a 24/7 production setup.

Option 2: Host It on a Server

For a bot that should stay online while your computer is off, you need a computer somewhere that stays available.

That computer can be a cloud server.

You upload your project, install the dependencies, add your environment variables, and start:

python bot.py

Now the cloud machine runs the program instead of your laptop.

Services designed for continuously running workloads can be used for this kind of application. For example, Render currently provides a Background Worker service type for continuously running processes that don't need to receive incoming web traffic.

But you should check the provider's current pricing and service limitations before deploying. Free hosting tiers aren't necessarily designed for an always-on Discord bot, and a "free forever" 24/7 setup isn't something you should assume a hosting platform will provide.

What "Forever" Actually Means

There isn't really a magical:

ONLINE_FOREVER = True

setting.

A bot can stay online continuously only as long as the computer or server running it continues operating.

Even a professionally hosted bot can go offline because of:

• Server maintenance

• Deployments

• Bugs

• Network problems

• Provider outages

• Invalid credentials

• API changes

• Billing or account issues

So the realistic goal is to keep the bot running automatically and restart it when something goes wrong.

That is what production hosting is designed to help with.

If your provider supports automatic restarts, enable them.

You can also make your Python code fail clearly when an important environment variable is missing:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

A clear error is much easier to debug than a mysterious bot that simply doesn't appear online.

Don't Try to "Keep It Awake" With Random Tricks

You may find tutorials suggesting that you deploy a web server and repeatedly ping it from another service to prevent a free hosting instance from sleeping.

Be careful with that approach.

Hosting providers change their free-tier rules, and attempting to work around those limits can violate their terms.

If you need an actually persistent bot, use a hosting option that explicitly supports the workload.

For example, a background worker is designed for continuously running processes. That's much cleaner than trying to convince a web service that your Discord bot is secretly a website.

Additional Features and Where to Go Next

Now that you have a working Discord bot, there are plenty of directions you can take the project next.

You could turn the storytelling system into a more complete game by adding an inventory, multiple chapters, puzzles, or different endings. You could also replace text-based commands with Discord slash commands and buttons to make the bot easier to interact with.

If you're interested in AI, you could expand the chat system by giving the bot different personalities, adding carefully limited conversation context, or using AI to generate parts of the stories.

You could also add moderation features, daily story prompts, or other commands that fit the kind of Discord community you're building.

These are ideas for extending the project rather than features we'll build step by step in this tutorial. The important thing is that you now have the foundation to experiment with them yourself.

Start with one small feature, figure out how it works, and build from there. You don't need to turn the bot into a massive project all at once.

The more you experiment with the code, the more you'll start seeing how Python, Discord, databases, and AI can work together in a real application.

Test Everything Locally First

Before deploying, test:

!hello
!story
!choose left
!choose right
!chat hello
!chat I want to learn Python
!support I'm stressed
!help

Then test weird inputs:

!choose banana
!chat
!support
!unknowncommand

You want to discover bugs while you're sitting in front of your computer, not three days later when someone tells you:

"Your bot has been broken since Tuesday."

Deploying the Bot

First, make sure your project contains:

discord-story-bot/
│
├── bot.py
├── requirements.txt
├── .gitignore
└── .python-version

A .python-version file can contain something like:

3.13

Using a version file makes your deployment environment more predictable. Render currently supports specifying a Python version through .python-version or an environment variable.

Your requirements.txt should contain your dependencies.

For example:

discord.py
python-dotenv

For deployment, you generally don't need the local .env file.

Instead, add:

DISCORD_TOKEN

as an environment variable in your hosting provider's dashboard.

That way the secret isn't stored inside your repository.

The Start Command

Your deployment service needs to know what to run.

For this project, the start command is:

python bot.py

The important thing is that the process doesn't immediately exit.

A Discord bot stays alive because bot.run(TOKEN) starts the Discord connection and keeps the program running.

If your hosting service supports background workers, that's a natural fit for a bot like this because the bot doesn't need to serve normal HTTP requests. Render specifically describes background workers as continuously running services that don't receive incoming network traffic.

Remember: Keep Your Secrets Secret

This is worth repeating because it causes a lot of beginner projects to get compromised.

Never commit this:

bot.run("YOUR_REAL_TOKEN")

Never upload:

.env

Never paste your actual token into a public GitHub issue.

If a token accidentally becomes public, treat it as compromised and regenerate it.

Environment variables are your friend.

What You Learned

You've now built a Discord bot that demonstrates several real programming concepts.

You learned how to:

• Create a Discord application

• Connect Python to Discord

• Use discord.py

• Configure Gateway Intents

• Create commands

• Use asynchronous functions

• Read command arguments

• Generate random stories

• Store temporary user state

• Create a basic chat system

• Create a mental-wellness support feature

• Handle command errors

• Keep secrets out of source code

• Prepare a project for deployment

• Think about persistent hosting

And underneath all those features, the architecture is still surprisingly simple:

User sends command
        ↓
Discord receives message
        ↓
discord.py receives event
        ↓
Python function runs
        ↓
Bot generates response
        ↓
Discord displays response

You don't need thousands of lines of code to get started.

You need a clear idea, a few Python concepts, and the willingness to keep debugging when something inevitably breaks.

Final Thoughts

The coolest part of this project isn't really the Discord bot. It's what the project teaches you.

And once you understand the pieces, you can reuse the same ideas in countless projects.

A Discord bot can become a game, which could become a web application, which could also become a larger software project.

And suddenly you're not just learning Python syntax anymore. You're learning how software actually gets built, one command at a time.

Happy coding!

Foundation Models is Apple's Swift framework for working with large language models. It's the on-device model behind Apple Intelligence, Apple's Private Cloud Compute, or another provider's server model.

This tutorial targets the on-device model: you send it a prompt and it runs entirely on the Mac's own hardware locally, free-per-call, and offline-friendly.

Paired with Apple Vision for reading images on device, that's enough to build real AI features like summaries, classification, and structured extraction without the data ever leaving your machine.

Table Of Contents

• What You Will Build

• Prerequisites

• Why a macOS Companion App?

• Foundation Models Can't Read Images Directly

• Project Structure

• Build the React App

  • Check Companion Health

  • Convert the Image to Base64

  • Analyze Immediately After Upload

  • Send the Image to the Companion

  • Render the JSON Output

• Build the macOS Companion App

• Check Foundation Models Availability

• Extract Text with Apple Vision

• Ask Foundation Models to Explain the Vision Output

• Return JSON to the Browser

• Run the App

• Conclusion

• Resources

What You Will Build

You'll build Vision Bridge, a web app that sends an image to a local macOS companion. The companion reads the image with Apple Vision, reasons about it with Foundation Models, and returns structured JSON to the browser: private, on-device AI behind a plain web interface.

You can find the complete source code in this GitHub repository: github.com/03balogun/vision-bridge.

The goal isn't to build a giant product but rather to understand the architecture behind how this works.

Vision Bridge has two parts:

• A React app with a split-screen interface.

• A macOS companion app that exposes a local API.

The React app has:

• An image upload area

• An image preview

• Automatic analysis after upload

• A JSON output viewer

• A companion health status indicator

The macOS companion app has:

• GET /v1/health

• POST /v1/analyze-image

• Apple Vision OCR

• Foundation Models availability checks

• Foundation Models reasoning over Vision output

The final response looks like this:

{
  "support": {
    "visionAvailable": true,
    "foundationModelAvailable": true,
    "foundationModelStatus": "available"
  },
  "image": {
    "filename": "screenshot.png",
    "contentType": "image/png",
    "byteCount": 1048576,
    "width": 1440,
    "height": 900
  },
  "vision": {
    "detectedText": [
      {
        "text": "Build failed",
        "confidence": 0.96,
        "boundingBox": {
          "x": 0.12,
          "y": 0.31,
          "width": 0.45,
          "height": 0.08
        }
      }
    ]
  },
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

Prerequisites

To follow along, you need:

• macOS 26 or newer

• Xcode with the macOS 26 SDK

• Node.js 20 or newer

• Basic React knowledge

• Basic Swift knowledge

• A Mac that supports Apple Intelligence

Foundation Models availability depends on the Mac, the OS version, and Apple Intelligence settings. The companion checks this at runtime, which we'll cover below.

Why a macOS Companion App?

You can't write this in a regular React app:

import FoundationModels from "apple-frameworks";

That API doesn't exist in the browser. A native macOS app, however, can use any Apple framework, so the companion acts as a local bridge. The same pattern works for any native capability the web platform doesn't expose.

Foundation Models Can't Read Images Directly

The public Foundation Models framework is a language model interface. It doesn't currently expose direct image input the way a multimodal cloud model might, so this tutorial never sends the image to the model. Instead, the companion feeds the Vision OCR observations and image metadata into the prompt. The model reasons over structured text, never the original pixels.

That split plays to each framework's strength: Vision is excellent at pulling machine-readable information out of images, and Foundation Models turns that information into summaries, labels, explanations, and structured output.

The above diagram shows the round trip that the rest of this tutorial builds. The browser sends the uploaded image as base64 JSON over localhost to the Swift companion. Inside the companion, Apple Vision runs OCR on the image and produces text observations: the recognized strings, their confidence scores, and their bounding boxes.

Those observations, not the image itself, are formatted into a prompt for Foundation Models, which generates a summary, description, and tags. The companion then bundles the Vision output and the model output into one JSON response and returns it to the browser.

Project Structure

Create a project with this structure:

vision-bridge/
  apps/
    web/
      src/
        main.tsx
        styles.css
      package.json
      vite.config.ts
    macos-companion/
      Package.swift
      Sources/
        VisionBridgeCompanion/
          main.swift
  package.json
  README.md

The root package.json gives us a few convenient commands:

{
  "scripts": {
    "dev": "npm --workspace apps/web run dev",
    "build": "npm --workspace apps/web run build",
    "companion": "swift run --package-path apps/macos-companion VisionBridgeCompanion"
  },
  "workspaces": ["apps/web"]
}

Build the React App

The web app is intentionally simple. It has one job: let the user pick an image and show the JSON returned by the companion.

The web app uses Vite, React, Lucide icons, and a JSON viewer:

{
  "dependencies": {
    "@vitejs/plugin-react": "^6.0.3",
    "lucide-react": "^0.468.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-json-view-lite": "^2.5.0",
    "vite": "^8.1.3"
  }
}

After defining the dependencies, install them:

npm install

The API base URL points to the local companion:

const API_BASE_URL = "http://127.0.0.1:43119";

Check Companion Health

The web app pings the companion so the UI can show whether the native bridge is online:

async function checkHealth() {
  setHealthError(null);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/health`);
    if (!response.ok) {
      throw new Error(`Health check failed with ${response.status}`);
    }

    const payload = await response.json();
    setHealth(payload);
  } catch (error) {
    setHealth(null);
    setHealthError(error instanceof Error ? error.message : "Companion unavailable");
  }
}

Convert the Image to Base64

When the user selects a file, the app converts it to base64 so it can be sent as JSON:

function readFileAsBase64(file: File) {
  return new Promise<string>((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const result = String(reader.result);
      resolve(result.includes(",") ? result.split(",")[1] : result);
    };
    reader.onerror = () => reject(reader.error);
    reader.readAsDataURL(file);
  });
}

This isn't the only way to upload files. You could also use multipart/form-data, but JSON keeps the demo easy to inspect.

Analyze Immediately After Upload

The app starts analysis as soon as an image is uploaded:

async function handleFile(file: File) {
  if (!file.type.startsWith("image/")) {
    setError("Choose a PNG, JPEG, HEIC, or another browser-readable image.");
    return;
  }

  const base64 = await readFileAsBase64(file);
  const nextImage = {
    file,
    previewUrl: URL.createObjectURL(file),
    base64,
  };

  setSelectedImage(nextImage);
  setAnalysis(null);
  setError(null);
  setCopied(false);

  analyzeImage(nextImage);
}

handleFile does the preparation work for every new image. It rejects anything that isn't a browser-readable image, converts the file to base64, and builds a single object holding everything the rest of the flow needs: the original File (for its name and MIME type), an object URL for the preview, and the base64 payload for the API call.

It then clears out the previous run the old analysis, any error message, and the "copied" indicator so the UI never shows results from the last image next to a new one. Finally, it kicks off analyzeImage(nextImage) immediately.

Note that it passes the fresh object directly instead of relying on the selectedImage state: React state updates don't apply until the next render, so reading the state here would still give you the previous image.

The Analyze button still exists in the UI, but it works as a manual rerun button.

Send the Image to the Companion

Here's the core request:

const analysisRequestId = useRef(0);

async function analyzeImage(image = selectedImage) {
  if (!image) {
    setError("Choose an image first.");
    return;
  }

  const requestId = analysisRequestId.current + 1;
  analysisRequestId.current = requestId;

  setRequestState("loading");
  setError(null);
  setCopied(false);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/analyze-image`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        filename: image.file.name,
        mimeType: image.file.type || "application/octet-stream",
        base64: image.base64,
      }),
    });

    const payload = await response.json();

    if (requestId !== analysisRequestId.current) {
      return;
    }

    if (!response.ok) {
      throw new Error(payload.error?.message ?? `Analysis failed with ${response.status}`);
    }

    setAnalysis(payload);
    setRequestState("success");
  } catch (error) {
    if (requestId !== analysisRequestId.current) {
      return;
    }

    setRequestState("error");
    setError(error instanceof Error ? error.message : "Could not analyze image");
  }
}

This function is the entire client side of the bridge. It flips requestState to loading (which drives the spinner and disables the button), then sends a POST to /v1/analyze-image with a JSON body containing three fields: the filename, the MIME type, and the base64 image data. That body maps one-to-one onto the AnalyzeImageRequest struct the Swift companion decodes later.

Notice that the response is parsed as JSON before checking response.ok. That's deliberate: when the companion rejects a request (bad base64, oversized image), it still returns a JSON body with an error.message field, so the UI can show the companion's own explanation instead of a generic status code. On success, the payload goes straight into state, and the JSON viewer re-renders with the result.

The requestId bookkeeping guards against stale responses. If a user uploads a second image while the first is still analyzing, whichever request finishes last would win, and OCR plus model generation takes long enough that responses can genuinely arrive out of order. So every call increments a counter stored in a ref and remembers its own ID.

After the await, it checks whether it's still the newest request; if a newer upload started in the meantime, the older response is silently discarded instead of overwriting the latest image's result. The same check runs in the catch block, so an old failure can't clobber a newer success either. If you also want to cancel the in-flight HTTP request rather than just ignore its result, an AbortController is the natural next step.

Render the JSON Output

The output pane uses react-json-view-lite:

<JsonView
  data={jsonData}
  shouldExpandNode={allExpanded}
  style={jsonViewTheme}
/>

Build the macOS Companion App

The companion is a Swift command-line app. It exposes a small local HTTP API.

If you come from the web side, the mapping is simple: Swift Package Manager is Swift's npm, Package.swift is its package.json, and swift run is its npm start. It ships with Xcode, so there's nothing extra to install.

The Package.swift file looks like this:

// swift-tools-version: 6.0

import PackageDescription

let package = Package(
    name: "VisionBridgeCompanion",
    platforms: [
        .macOS("26.0")
    ],
    products: [
        .executable(
            name: "VisionBridgeCompanion",
            targets: ["VisionBridgeCompanion"]
        )
    ],
    targets: [
        .executableTarget(
            name: "VisionBridgeCompanion"
        )
    ]
)

The companion imports the Apple frameworks it needs:

import Foundation
import FoundationModels
import ImageIO
import Network
import Vision

It listens on 127.0.0.1:43119:

private let defaultPort: UInt16 = 43119

The app exposes two routes:

switch (request.method, request.path) {
case ("GET", "/v1/health"):
    let health = HealthResponse(support: ModelSupport.current)
    return try json(health)

case ("POST", "/v1/analyze-image"):
    let payload = try JSONDecoder().decode(AnalyzeImageRequest.self, from: request.body)
    let response = try await service.analyze(payload)
    return try json(response)

default:
    return try json(
        ErrorResponse(error: APIErrorPayload(message: "Route not found")),
        status: .notFound
    )
}

This switch is the companion's entire routing layer — no web framework, just pattern matching on the method and path.

The two routes split the work cleanly:

• GET /v1/health is the cheap, read-only route. It runs no analysis, it just reports whether Vision and Foundation Models are usable on this Mac via ModelSupport.current (covered in the next section). The React app calls it on load to render the online/offline status pill, so the user knows the bridge is up before they upload anything.

• POST /v1/analyze-image is where the real work happens. It decodes the request body into an AnalyzeImageRequest (with the same filename, mimeType, and base64 fields the browser sent) and hands it to the analysis service. This validates the image, runs Vision OCR, prompts Foundation Models, and returns the combined result. The try await matters here: analysis is asynchronous, and the route simply waits for it before serializing the response.

Anything else falls through to a JSON 404, so even unknown routes respond in the same format the browser already knows how to parse.

Errors work the same way: thrown errors are caught in one place and converted into JSON error responses with an appropriate status code, which is exactly what the web app's payload.error?.message check reads.

One practical detail: because the browser calls the companion from a different origin (the Vite dev server), every response also carries CORS headers, and the router answers preflight OPTIONS requests with an empty 204. Without that, the browser would block the fetch before it ever reached these routes.

Check Foundation Models Availability

The companion shouldn't assume that the model is available. Check it first:

private struct ModelSupport: Encodable {
    let visionAvailable: Bool
    let foundationModelAvailable: Bool
    let foundationModelStatus: String

    static var current: ModelSupport {
        let model = SystemLanguageModel.default

        switch model.availability {
        case .available:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: true,
                foundationModelStatus: "available"
            )

        case .unavailable(let reason):
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.\(reason.description)"
            )

        @unknown default:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.unknown"
            )
        }
    }
}

A user might have an unsupported Mac, Apple Intelligence might be disabled, or the model might not be ready yet. The response tells the browser which case it's dealing with.

Extract Text with Apple Vision

The companion decodes the base64 image, checks its metadata, then runs Vision OCR.

Here's the text recognition flow:

private func recognizeText(in imageData: Data) async throws -> [DetectedText] {
    var request = RecognizeTextRequest()
    request.recognitionLevel = .accurate
    request.automaticallyDetectsLanguage = true
    request.usesLanguageCorrection = true

    let observations = try await request.perform(on: imageData)

    var detectedText: [DetectedText] = []

    for observation in observations {
        guard let candidate = observation.topCandidates(1).first else {
            continue
        }

        let bounds = NormalizedBox.from(points: [
            observation.topLeft,
            observation.topRight,
            observation.bottomRight,
            observation.bottomLeft
        ])

        detectedText.append(DetectedText(
            text: candidate.string,
            confidence: Double(candidate.confidence),
            boundingBox: bounds
        ))
    }

    return detectedText
}

Vision gives us structured observations:

• recognized text

• confidence scores

• normalized bounding boxes

Those observations become the model’s context.

Ask Foundation Models to Explain the Vision Output

Now the companion creates a prompt from the image metadata and OCR results.

Notice the instruction:

You cannot see the original image. Use only the metadata and OCR observations below.

That keeps the model honest. It shouldn't pretend to see pixels it never received.

Here's the prompt shape:

let textPreview = detectedText
    .prefix(30)
    .map { "- \($0.text) (confidence: \(String(format: "%.2f", $0.confidence)))" }
    .joined(separator: "\n")

let prompt = """
You are summarizing Apple Vision OCR output for a developer tool named Vision Bridge.
You cannot see the original image. Use only the metadata and OCR observations below.

Image:
- filename: \(image.filename)
- content type: \(image.contentType)
- size: \(image.width ?? 0)x\(image.height ?? 0)

OCR observations:
\(textPreview.isEmpty ? "- No text detected." : textPreview)

Return a compact JSON object with these exact keys:
summary: one sentence
description: one short paragraph
suggestedTags: 3 to 6 short tags
possibleUses: 3 to 5 practical use cases for this kind of image analysis
"""

Then call the model:

let session = LanguageModelSession(
    model: .default,
    instructions: "Return valid JSON only. Do not include Markdown fences."
)

let response = try await session.respond(to: prompt)
let raw = response.content.trimmingCharacters(in: .whitespacesAndNewlines)

Even when you ask for JSON, always validate the output. Models can still return Markdown fences or malformed text. The sample app strips simple Markdown code fences and falls back to a raw response if parsing fails.

Return JSON to the Browser

The companion combines the support state, image metadata, Vision results, and model output:

return AnalyzeImageResponse(
    support: support,
    image: metadata,
    vision: VisionPayload(detectedText: detectedText),
    model: modelInsight
)

The browser doesn't need to know how Vision or Foundation Models work. It just receives JSON. The native app owns the native capabilities, while the web app owns the interface.

It's worth pausing on what each of the four blocks actually gives you, because they're not all the same kind of data:

• support tells you what was possible on this Mac. If foundationModelAvailable is false, the model block still exists but contains a fallback message rather than real analysis, and the foundationModelStatus string (for example, unavailable.appleIntelligenceNotEnabled) tells the UI why, so it can explain rather than silently degrade.

• image echoes back the file's metadata plus the measured pixel dimensions. It's useful as a sanity check, and you need the width and height to do anything spatial with the Vision results.

• vision is the ground truth. Each entry in detectedText is a string Vision actually found, with a confidence score between 0 and 1 and a normalized bounding box: coordinates expressed as fractions of the image size, so x: 0.12, width: 0.45 means "starts 12% from the left and spans 45% of the width." Because the boxes are normalized, you can draw highlight overlays on the preview at any display size by multiplying by the rendered dimensions. Low-confidence entries are worth filtering or flagging before you trust them.

• model is interpretation, not observation. The summary, description, suggestedTags, and possibleUses fields are generated by the language model from the OCR text. This is useful as alt text, captions, or tag suggestions, but they inherit whatever the OCR missed and should be treated as a draft, not a fact. When the model's output can't be parsed as JSON, rawResponse carries the unparsed text so nothing is lost.

For a screenshot of a failed build, the model block might come back like this:

{
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

That combination (exact text with positions from Vision, plus a human-readable interpretation from the model) is enough to build real features on top of a searchable screenshot library indexed by detectedText and suggestedTags, automatic alt text for uploaded images, or click-to-highlight overlays powered by the bounding boxes.

And because the prompt lives in the companion, changing what comes back (say, extracting line items from receipts instead of tagging screenshots) is a prompt edit, not an architecture change.

Run the App

Start the companion:

npm run companion

In another terminal, start the web app:

npm run dev

Open the Vite URL:

http://127.0.0.1:5173

If that port is busy, Vite will choose another one.

The companion should be available at:

http://127.0.0.1:43119

You can test it directly:

curl http://127.0.0.1:43119/v1/health

Expected response:

{
  "app": "Vision Bridge Companion",
  "ok": true,
  "support": {
    "foundationModelAvailable": true,
    "foundationModelStatus": "available",
    "visionAvailable": true
  },
  "version": "0.1.0"
}

Conclusion

You now have a React interface that uploads an image, a Swift companion that analyzes it with Apple-native frameworks, and structured JSON flowing between them.

Vision Bridge is intentionally small, but the bridge itself is reusable. Once you have a trusted native companion, a web app can do more than send prompts to a remote model: it can ask the Mac to work with local context, use any Apple framework, and return structured data the browser can render, store, or sync.

Resources

• Apple Foundation Models documentation

• Apple Vision documentation

The phrase has become a running joke in software, but it's rarely funny when it happens in production.

A feature passes every local test, the pull request gets approved, the deployment finishes successfully, and then users start reporting failures.

On-call engineers get paged. Incident channels fill up. A fix that took ten minutes to write takes four hours to trace back to a missing environment variable or a runtime version mismatch nobody noticed.

The strange part is that this still happens in 2026.

Modern development has better tooling than ever. Containers, automated testing, cloud infrastructure, CI/CD pipelines, infrastructure as code, and AI coding assistants have all made building software considerably faster.

And yet engineering teams running customer-facing applications continue to lose significant time chasing bugs that only appear outside a developer's laptop.

One industry survey found that developers spend roughly 40% of their time on tasks unrelated to writing features,  and environment debugging is a leading culprit.

The reason isn't that engineers are careless. Most software doesn't fail because of bad code. It fails because code runs inside an environment, and those environments are rarely identical.

The gap between a developer's laptop and a production cluster is still one of the most consistent sources of engineering waste these days.

The real question is no longer why this problem exists. Every experienced engineering team understands environment drift. The better question is why so many product teams are still spending engineering time managing it.

What We'll Cover:

• Every Machine Tells a Slightly Different Story

• Dependencies Are Moving Targets

• Configuration Causes More Incidents Than Code Does

• The Real Cost of Managing Multiple Environments

• Why Are Teams Still Managing This Themselves in 2026?

• Local Success Doesn't Reflect Production Conditions

• Why Are More Engineering Teams Choosing Managed Platforms?

• What a Basic PaaS Setup Actually Looks Like

• Consistency is an Ownership Question, Not a Tooling Question

Every Machine Tells a Slightly Different Story

A production application depends on much more than source code.

It depends on the operating system, runtime versions, environment variables, databases, third-party services, networking rules, file permissions, installed libraries, and CPU architecture.

A developer running Node.js 24 LTS may be pairing with a teammate still on 22. One laptop has a newer OpenSSL version installed as a transitive dependency update. Another has a cached build artefact from three months ago that quietly changed behaviour after a library patch.

None of these differences looks significant on their own. Together, they create a local environment that behaves differently from every other environment in the pipeline.

This is how a test suite passes green on a developer's machine and fails in CI twenty minutes later. It's how an application boots cleanly on macOS but crashes on the Debian container your cloud provider runs.

It's why a microservice that handled 500 requests per second last Tuesday starts timing out this Monday after what appeared to be an unrelated dependency bump.

The code hasn't changed. The environment has.

Dependencies Are Moving Targets

Package managers have made software development productive, but they've also dramatically increased the surface area of a running application.

A typical Node.js web application today has between 500 and 1,500 packages in its dependency tree, including indirect dependencies, even when a developer explicitly installs only a handful.

A Python service using common data processing and web frameworks can pull in 200 to 400 packages. Most engineers have no direct relationship with the vast majority of packages their application ships.

When dependency versions aren't locked correctly, two developers installing the same project on the same day can receive materially different software stacks. Lock files like package-lock.json, pnpm-lock.yaml, poetry.lock, Cargo.lock exist precisely to prevent this, and they help. But they're one layer of control in a much larger consistency problem.

Runtime versions still differ. System libraries still differ. Base OS images in containers drift across patch cycles. A Docker image built from node:22 today isn't the same image that gets built in six weeks when the upstream tag has been updated. Teams that don't pin their base images precisely are unknowingly accepting environment drift at the foundation of every deployment.

Configuration Causes More Incidents Than Code Does

Many of the most disruptive production incidents on engineering teams have nothing to do with programming logic.

They come from configuration.

An environment variable is missing in the new deployment target. A database connection string points to staging instead of production. A feature flag is set to true in the developer's .env file but defaults to false in the deployed service, silently disabling a critical code path. An API key was rotated but the secret manager reference was updated in one environment and not the other.

These mistakes are common, and genuinely difficult to prevent, because configuration lives outside the application. It's managed separately, documented inconsistently, and almost never covered by standard test suites.

Post-incident reviews regularly surface configuration drift as the root cause of outages that took hours to diagnose because the application code looked completely correct.

The problem compounds across environments. A team running development, staging, pre-production, and production has four separate configuration states to keep aligned.

When an engineer adds a new environment variable, that change has to propagate through every environment reliably. In practice, it often doesn't. One environment gets missed. An old value lingers. The application behaves differently, and the investigation starts from scratch.

The Real Cost of Managing Multiple Environments

Engineering leadership often underestimates how much time is consumed by environment management, not because it's hard to observe, but because it's distributed across dozens of small tasks that never appear as line items.

Someone updates the Node runtime in the base Docker image and spends an afternoon chasing a downstream test failure that turned out to be a transitive dependency incompatibility.

Someone provisions a new staging environment and spends a day replicating the production configuration by hand. Someone rotates credentials, misses one service, and triggers a silent failure that takes until the next deployment cycle to surface. Someone joins the team and spends the first two days getting a local environment running instead of shipping work.

Estimates from engineering productivity research suggest that infrastructure and environment-related tasks consume between 15 - 25% of total engineering capacity at companies that own their own deployment infrastructure. For a team of ten engineers, that's effectively two to three people running hard and producing no customer-facing output.

This is the cost that doesn't appear on sprint boards. It lives in Slack threads, in incident retrospectives, and in the quiet acknowledgement that the team is slower than it should be.

None of this work appears on a roadmap. Customers never ask for it. It doesn’t create differentiation. Yet product teams spend hundreds of engineering hours every year maintaining consistency between environments simply to keep software deployable. Environment drift isn't just a reliability problem. It's an engineering capacity problem.

Why Are Teams Still Managing This Themselves in 2026?

Given all of this, the reasonable question is why so many engineering teams are still owning this complexity directly.

Part of the answer is inertia. Teams that built their infrastructure several years ago, when Kubernetes was the obvious answer to every scaling question and "we control our own stack" felt like a competitive advantage, now maintain that infrastructure because changing it has a cost.

The investment is already made. The tooling is already familiar. The pain is distributed and chronic rather than acute, which makes it easier to absorb than to address.

Part of the answer is organisational habit. Hiring a platform or DevOps engineer to manage infrastructure feels like the right response to environmental problems. But that engineer becomes responsible for maintaining the consistency layer indefinitely. Patching base images, updating runtime versions, managing certificate renewals, and debugging networking issues across environments, rather than delivering product leverage.

Part of the answer is a belief that more control produces better outcomes. Running your own infrastructure gives complete visibility into every configuration decision.

But complete control also means complete responsibility. Every decision the platform team makes is a decision the platform team must maintain, document, and revisit every time something upstream changes.

Most product engineering teams aren't in the infrastructure business. They're in the business of building software for customers, and every hour spent on environment consistency is an hour not spent on that.

The honest answer is that many teams are managing this complexity themselves because they haven't yet found a clear path to stopping.

Local Success Doesn't Reflect Production Conditions

One consistent failure mode is treating a passing local test as a signal that a deployment is safe.

Production environments impose conditions that development machines never encounter. A service that starts cleanly on a laptop with no concurrent users will behave differently when handling 2,000 requests per second with three application instances competing for a shared database connection pool.

A background job that completes in milliseconds locally may time out in production when it runs simultaneously with twelve other jobs against a database under real write load.

Staging environments exist to surface these differences before they reach users. But staging only provides value when it actually resembles production, like the same infrastructure, the same runtime versions, the same configuration shape, same network topology.

Many teams treat staging as a best-effort approximation. Over time, configuration drift between staging and production means that staging stops catching the failures it was designed to catch. Teams end up discovering environment-related issues in production anyway, which is the worst place to find them.

Maintaining genuine parity across three or four environments is expensive and requires continuous attention. Infrastructure updates must be applied uniformly. Runtime versions must stay synchronised. Configuration must be propagated reliably.

Without active discipline, staging drifts away from production, and the safety net disappears.

Why Are More Engineering Teams Choosing Managed Platforms?

At some point, every engineering organisation has to ask a more fundamental question. Should we keep investing engineering time into maintaining environments, or should we move that responsibility to a platform built for it?

This is the context in which Platform as a Service has become a more serious consideration for teams that previously managed their own infrastructure.

A well-designed PaaS doesn't remove engineering responsibility. It relocates it.

Developers still write code. They still define environment variables and build processes. They still decide what their application needs. The difference is that the platform provides a consistent, maintained runtime across every environment like development, staging, and production, without the team owning the underlying infrastructure.

The same application definition runs everywhere. Environment parity becomes a property of the platform rather than a discipline the team has to enforce continuously.

This matters most to engineering teams with real deployment velocity, the teams shipping multiple times per day, running several services, and operating with the expectation that deployments are predictable.

When the platform standardises the environment, deployments stop being experiments. Engineers stop discovering production-only failures at the worst possible time.

The operational tradeoff is real. Some organisations require control over their infrastructure for compliance, regulatory, or architectural reasons that a PaaS can't accommodate. But many teams that believe they need that control have never closely examined the cost of maintaining it.

The question isn't whether owning infrastructure gives you control. It's whether that control is producing outcomes that justify the engineering capacity it consumes.

What a Basic PaaS Setup Actually Looks Like

The argument for a managed platform is easier to evaluate with a concrete picture of what adopting one involves. The details vary across providers like Render, Railway, Sevalla, etc, but the setup's shape is remarkably consistent and smaller than most teams expect.

Step 1: Connect your repository. Every mainstream PaaS starts from your Git repository. You authorise the platform against GitHub or GitLab, point it at a repo, and choose a branch to deploy from. From that moment, the platform watches for pushes. There's no CI pipeline to write for the basic case, since build-and-deploy on push is the default behaviour.

Step 2: Define the application, once, in a file. Instead of configuring servers, you describe what your application is: the runtime, the build command, the start command, and the services it needs. Most platforms let you do this through a dashboard, but the better practice is a declarative file that lives in the repo.

services:
  - type: web
    name: my-api
    runtime: node
    buildCommand: npm ci
    startCommand: npm run start
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: my-api-db
          property: connectionString
      - key: NODE_ENV
        value: production

databases:
  - name: my-api-db
    plan: basic

This file is the payoff of the whole model. It's the single source of truth for how the application runs, it's version-controlled alongside the code, and, critically, it's the same definition in every environment.

The drift described earlier in this article, where staging quietly diverges from production, has nowhere to live, because there is no second copy of the environment to fall out of sync.

Step 3: Set your environment variables in the platform, not in files. Secrets and configuration move out of scattered .env files and into the platform's environment settings, scoped per environment.

When an engineer adds a new variable, the platform surfaces it in one place rather than requiring a manual update across four deployment targets. Most platforms also support environment groups, so shared configuration is defined once and inherited.

Step 4: Attach managed services. Databases, caches, and cron jobs are provisioned by the platform rather than installed and patched by your team.

In the example above, the database is declared in the same file as the application, and its connection string is injected automatically, so there's no connection string to copy incorrectly into staging.

Step 5: Push, and let preview environments do the rest. This is where the parity argument becomes tangible. Most modern PaaS providers spin up a preview environment for every pull request: a full, disposable copy of the application, built from the same definition file, running on the same infrastructure as production.

"Works on my machine" stops being the standard of evidence, because every reviewer is looking at the code running in a production-shaped environment before it merges. When the PR closes, the environment is destroyed.

That's the whole setup. For a typical web service, going from repository to a deployed, auto-updating application with a managed database takes an afternoon, not a quarter.

For teams with existing infrastructure, the sensible starting point isn't a migration project. It's one service , ideally something low-risk and self-contained, like an internal tool or a background worker.

Run it on a platform for a month, compare the operational load against its Kubernetes-hosted siblings, and let the result inform the larger decision. Most teams that make this comparison discover the question isn't whether the platform can handle their workload. It's how much of their engineering week they'd been spending to get a worse version of the same guarantee.

Consistency is an Ownership Question, Not a Tooling Question

"It worked on my machine" gets framed as a process problem, or a testing problem, or occasionally a culture problem. The real framing is more useful: it's an ownership problem.

Every difference between environments like runtime versions, dependency trees, configuration values, and infrastructure state increases the probability that software behaves unexpectedly in production. The conventional response is to invest in better tooling: stricter lock files, more comprehensive CI, better container discipline, more thorough staging.

All of these reduce the problem. None of them eliminates the underlying dynamic, which is that the team is responsible for the consistency of every environment it owns.

The teams that have largely solved deployment reliability in 2026 aren't necessarily the ones with the most sophisticated infrastructure. Many of them are the ones that have reduced the number of environments they own and maintain.

They have moved infrastructure decisions to platforms designed to handle them, and redirected that engineering capacity toward problems that are actually differentiated: the product, the performance, the reliability of the application itself.

Environment consistency is a solvable problem. The remaining question is ownership. Every product team must decide whether maintaining infrastructure is part of its competitive advantage or simply an operational burden it has accepted over time. More engineering teams are concluding that their advantage comes from shipping product, not managing environments.

"I just want something like Heroku."

I've said it myself. And I was wrong about what I meant.

Not wrong that Heroku was good. It was genuinely great, and the people who built it understood something most infrastructure companies still haven't internalized.

But when Salesforce killed the free tier in 2022 (and recently when it announced the end of sale for new enterprise customers) and the migration scramble started, something interesting happened: almost everyone reached for the wrong lesson.

They thought the thing people loved about Heroku was easy deploys. So they built easier deploys.

But that wasn't it.

What Heroku Actually Did

When I was running a side project on Heroku sometime around 2019 or so, I didn't think about infrastructure at all. I pushed to Git, it deployed. My Postgres was there. If I needed a queue, I added a plugin. Everything lived in the same mental model, and that mental model took up approximately zero space in my head on a normal workday.

The thing Heroku sold wasn't a deployment pipeline. It was cognitive zero. The absence of infrastructure as a thing you had to think about.

That distinction matters more than it sounds. Because when you have to think about infrastructure, even a little, it bleeds into everything.

You make product decisions based on what's easy to deploy, not what's right. You delay shipping because you're not sure how the pieces connect. You spend a Friday afternoon debugging why your app can't reach its own database across two vendor networks instead of building the feature that would've landed three new customers.

Heroku removed all of that. One platform, everything pre-wired, one bill, one place to look when something breaks.

The Alternatives Got One Thing Right and Missed the Rest of the Point

After Heroku's free tier died, Render, Railway, and Fly.io stepped up. All three are genuinely better than wrangling EC2 yourself. I've used all of them. I have no interest in being unfair to any of them.

But here's what actually happens when you use them.

You deploy your app to Render. Then you provision a Postgres database, also on Render, and paste the connection string into your environment variables.

Then you realize you need background jobs, so you sign up for Upstash or add a Redis instance somewhere. Then you want object storage, so you create an S3 bucket on AWS because Render doesn't have that.

Now you have three dashboards, three billing relationships, three sets of network rules to get right, and the mental overhead of three vendors stitched together with environment variables and prayer.

Railway is closer to the old vision, and it feels more integrated. But it runs on AWS underneath. You're paying Railway's margin on top of Amazon's margin, which means you're paying the hyperscaler tax twice: once to Amazon for the actual compute, and once to Railway for the privilege of not talking to Amazon directly.

Fly.io made the most interesting bet: they went bare metal. Real hardware, no AWS underneath, which structurally breaks the double-margin problem. But the integration story never quite closed. Your Postgres on Fly is still a thing you wire up separately. The "everything connected" feeling that made Heroku feel magical isn't there. You're still the one holding the wires.

The Thing Nobody Talks About: Egress Charges Between Your Own Services

Here's something that took me longer to fully internalize than it should have.

When your app, your database, and your storage bucket live on different vendors, or even different services inside a cloud provider, data moving between them costs money. Not a lot, usually, until it is a lot.

An app that reads from a database 10,000 times a day, processes some results, and writes to S3 is moving data in three directions constantly. On a hyperscaler-backed platform, some of that movement crosses billing boundaries.

On a platform where compute, Postgres, storage, and queues all live on the same bare metal network? That movement is free, because it never leaves the building.

This isn't a hypothetical. It's a structural difference in how the platforms are architected, and it compounds over time in ways that don't show up clearly on any individual invoice.

"Opinionated" is Doing Real Work Here, Not Marketing Work

I've worked with teams that spent actual engineering hours debating which queue system to use. Not implementing it. Debating it. SQS vs. BullMQ vs. RabbitMQ vs. something someone read about on a blog three years ago.

The argument for an opinionated platform isn't that you're incapable of making that decision. It's that the decision doesn't matter as much as you think, and the time you spend making it is time you're not spending on the thing that actually differentiates your product.

Postgres is the right database for almost every startup that exists. S3-compatible storage handles almost every file storage use case. A reliable queue is a reliable queue. These aren't interesting decisions. They stopped being interesting about a decade ago. The interesting decisions are in your product.

An opinionated platform forces you to stop relitigating settled questions. That's not a limitation. That's the point.

The Lock-in Question, Answered Honestly

The most common pushback I hear when someone looks at a vertically integrated platform is: "What if I want to leave?"

It's a fair question and I used to ask it, too. Here's what I've realized: the lock-in concern is almost always theoretical, and it's usually raised by people who've never actually migrated off a platform.

Real lock-in requires something proprietary that your code depends on. A custom SDK that only works with that vendor. A query language that doesn't exist anywhere else. A deployment model that requires rewriting your app to leave.

If your app runs in a container, uses standard Postgres connection strings, speaks to S3 with an AWS SDK, and publishes jobs to a queue over a standard protocol, you're not locked in. You're just deployed somewhere. The migration path is a pg_dump, a bucket copy, and a new docker push. I've done migrations like that in a weekend.

The platforms that actually create lock-in are the ones that abstract everything into their own proprietary layer. Serverless functions with custom runtimes. Vendor-specific databases with proprietary query features. Edge compute that only exists on one network. Those are the things worth being suspicious of.

Where Each Alternative Actually Breaks Down

Render is the easiest to recommend and the easiest to outgrow. Deploy a Next.js app, get a managed Postgres, done.

The problem shows up around month three when you need background jobs and object storage. Render doesn't have either natively.

So you reach for Upstash for queues and AWS S3 for storage. Now you have three dashboards, three billing relationships, and three networks that have to trust each other. The deployment step takes minutes. Everything around it takes the afternoon.

Railway feels more integrated than Render and the DX is genuinely good. But it runs on AWS. That's not a criticism of the team. It's a structural fact that has downstream consequences. As I mentioned before, you're paying Railway's margin on top of Amazon's margin, and data moving between your app and your database may cross billing boundaries depending on how Railway has provisioned things. The cost doesn't look alarming on any single invoice. But it compounds.

Fly.io made the most interesting architectural bet. Real hardware, no hyperscaler underneath, which structurally breaks the double-margin problem. \

I've deployed on Fly and the performance at the edge is real. But compute and Postgres are still separate things you wire together. Storage is still an external conversation. The "everything connected" feeling isn't there because the connections are still yours to make.

What the "I Just Want Something Like Heroku" Crowd Actually Needs

I've thought about this a lot, and I think the nostalgia is real but misdirected.

People don't want Heroku specifically. They want the feeling that infrastructure is someone else's problem. Not because they can't handle it, but because handling it isn't why they got into building software. They want to push code and have things work. They want one place to look when things break. They want a bill they can understand.

The platforms that came after Heroku optimized for the wrong thing. They made the deployment step easier while leaving the integration work on you. They gave you a better on-ramp to the same fragmented landscape.

The more honest path is a platform that's made the architectural decisions Heroku never fully made: own the hardware, connect the services at the network level, charge one bill, and let the developer focus on code.

That's not nostalgia. That's just what the problem actually requires.\

Another Alternative to Heroku

Here is what I've been watching: Atlasflow. Bare metal, with compute, Postgres, S3-compatible storage, and queues on the same network before you ever touch them. And one bill.

I haven't run a production workload there yet, so I can't speak to reliability under pressure. That matters and I won't pretend it doesn't.

But the architectural argument is the most honest attempt I've seen at solving the actual problem rather than the symptom. Every other platform made deploy easier. Atlasflow is asking whether the integration should have been your problem in the first place.

That's not a small distinction. It's the whole thing.

I've been building production apps for close to a decade and belive me, you, the infrastructure landscape has gotten better in almost every measurable way. The integration problem is still mostly unsolved.

The gap between where you are and being able to build and deploy a production backend is smaller than you think.

The missing piece is not a new language. It's not a new paradigm. It's understanding how Dart behaves when there's no widget tree, no BuildContext, no Flutter framework – just a running process handling HTTP requests, talking to a database, and sending responses back to clients.

That's exactly what this article covers.

We're going to build a full User and Profile Management REST API from scratch using Dart and Shelf, connect it to a PostgreSQL database running in Docker, secure it with JWT authentication, and deploy it to Fly.io.

By the end, you'll have a working production-grade backend written entirely in Dart, the same language you already know.

This article is part of a series (of standalone articles) where we'll build the same project using three different frameworks. We'll use Shelf here, Serverpod in the next article, and Dart Frog in the one after that. This will let you directly compare how each framework approaches the same problem.

Table of Contents

• Prerequisites

• How Dart Works on the Server

• What is Shelf?

• Project Setup

  • Creating the Project

  • Project Structure

  • Database Setup with Docker

  • Environment Configuration

• Shelf Core Concepts

  • Handlers

  • Request and Response

  • Router

  • Pipeline and Middleware

• Connecting to PostgreSQL

  • The Database Connection Manager

  • Running Migrations

• Building the API

  • The User Model

  • The User Repository

  • User Handlers

  • The Profile Model

  • The Profile Repository

  • Profile Handlers

• Authentication

  • Password Hashing

  • JWT Token Generation and Validation

  • Auth Handlers

  • Auth Middleware

• Error Handling

• Wiring Everything Together

• Deployment

  • Dockerfile

  • Docker Compose for Local Production Testing

  • Deploying to Fly.io

• Testing the API

• Conclusion

Prerequisites

Before starting, you should have:

• Comfortable familiarity with Dart and Flutter development

• Understanding of REST API concepts, endpoints, HTTP methods, status codes

• Docker Desktop installed and running

• A Fly.io account (free tier is sufficient, fly.io)

• The Fly CLI installed (brew install flyctl on macOS, or the official installer on Windows/Linux)

• A PostgreSQL client for inspecting the database, like TablePlus or DBeaver – both work well

How Dart Works on the Server

When you run a Flutter app, the Flutter framework is doing an enormous amount of work, managing the widget tree, handling the render pipeline, coordinating state, and responding to platform events. Your Dart code sits on top of all of that.

On the server, none of that exists. There's no widget tree. There's no framework managing a UI lifecycle. There's just a Dart process running, listening on a port, receiving HTTP requests, doing work, and sending responses.

Dart's standard library, dart:io, has everything needed to do this at the lowest level:

import 'dart:io';

void main() async {
  final server = await HttpServer.bind('0.0.0.0', 8080);
  print('Server running on port 8080');

  await for (final request in server) {
    request.response
      ..statusCode = 200
      ..write('Hello from Dart')
      ..close();
  }
}

This is a working HTTP server in raw Dart. No packages, no framework. Every request comes in through the HttpServer stream, and you write directly to the response.

This works, but it scales poorly. As soon as you need routing, middleware, authentication, and structured error handling, raw dart:io becomes difficult to manage. That is the problem Shelf solves.

What is Shelf?

Shelf is a composable web server middleware library for Dart, maintained by the Dart team. It doesn't try to be a full framework – instead, it gives you the primitives to build one, or to assemble exactly what you need.

The Shelf mental model is built on four concepts:

• Handler: a function that takes a Request and returns a Response. Everything in Shelf is ultimately a handler.

• Middleware: a function that wraps a handler, adding behaviour before or after it runs. Logging, authentication, and error handling are all middleware.

• Pipeline: a chain of middleware with a handler at the end. Requests flow through the middleware chain before reaching the handler.

• Router: maps URL patterns and HTTP methods to specific handlers.

If you've used Flutter's Navigator or provider middleware concepts, the composition model will feel familiar. Small, single-responsibility pieces assembled into a working whole.

Project Setup

Creating the Project

Dart includes a server-side project template that gives us a clean starting point:

dart create -t server-shelf user_profile_api
cd user_profile_api

Add the dependencies we need to pubspec.yaml:

name: user_profile_api
description: User and Profile Management REST API built with Dart and Shelf
version: 1.0.0

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  shelf: ^1.4.1
  shelf_router: ^1.1.4
  postgres: ^3.3.0
  dart_jsonwebtoken: ^2.12.0
  bcrypt: ^1.1.3
  dotenv: ^4.1.0
  crypto: ^3.0.3

dev_dependencies:
  lints: ^3.0.0
  test: ^1.24.0

Run:

dart pub get

Project Structure

Now we'll build a backend project structure that Flutter engineers will find intuitive, that's familiar enough to navigate immediately, and that's correct enough for backend conventions:

user_profile_api/
  bin/
    server.dart              ← entry point
  lib/
    config/
      database.dart          ← connection manager
      env.dart               ← environment config
    handlers/
      auth_handler.dart      ← auth endpoints
      user_handler.dart      ← user endpoints
      profile_handler.dart   ← profile endpoints
    middleware/
      auth_middleware.dart   ← JWT validation
      error_middleware.dart  ← global error handling
      logger_middleware.dart ← request logging
    models/
      user.dart
      profile.dart
    repositories/
      user_repository.dart
      profile_repository.dart
    services/
      auth_service.dart      ← JWT + password logic
    router.dart              ← route definitions
  migrations/
    001_create_users.sql
    002_create_profiles.sql
  docker-compose.yml
  Dockerfile
  .env
  .env.example

This separation of concerns maps directly to what you'll already know if you're a Flutter engineer: models, repositories, and services are the same concepts. Handlers replace ViewModels or Controllers. Middleware replaces interceptors.

Database Setup with Docker

Create docker-compose.yml in the project root:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: user_profile_db
    environment:
      POSTGRES_DB: user_profile_api
      POSTGRES_USER: dart_user
      POSTGRES_PASSWORD: dart_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Start the database:

docker compose up -d

Verify that it's running:

docker compose ps
# user_profile_db   running   0.0.0.0:5432->5432/tcp

Environment Configuration

Create .env in the project root:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=user_profile_api
DB_USER=dart_user
DB_PASSWORD=dart_password
JWT_SECRET=your_super_secret_key_change_this_in_production
JWT_EXPIRY_HOURS=24
PORT=8080

Create .env.example with the same keys but no values. This is what you commit to Git:

DB_HOST=
DB_PORT=
DB_NAME=
DB_USER=
DB_PASSWORD=
JWT_SECRET=
JWT_EXPIRY_HOURS=
PORT=

Add .env to .gitignore:

.env

Create lib/config/env.dart:

import 'package:dotenv/dotenv.dart';

class Env {
  static late final DotEnv _env;

  static void load() {
    _env = DotEnv(includePlatformEnvironment: true)..load();
  }

  static String get dbHost => _env['DB_HOST'] ?? 'localhost';
  static int get dbPort => int.parse(_env['DB_PORT'] ?? '5432');
  static String get dbName => _env['DB_NAME'] ?? 'user_profile_api';
  static String get dbUser => _env['DB_USER'] ?? 'dart_user';
  static String get dbPassword => _env['DB_PASSWORD'] ?? '';
  static String get jwtSecret => _env['JWT_SECRET'] ?? '';
  static int get jwtExpiryHours => int.parse(_env['JWT_EXPIRY_HOURS'] ?? '24');
  static int get port => int.parse(_env['PORT'] ?? '8080');
}

includePlatformEnvironment: true means the Env class reads from both the .env file and real system environment variables, so the same code works locally with a .env file and in production with injected environment variables.

Shelf Core Concepts

Before building the API, it's worth understanding each Shelf concept properly – not just what it does, but why it's designed the way it is.

Handlers

A handler is the most fundamental unit in Shelf. It's simply a function:

import 'package:shelf/shelf.dart';

Response helloHandler(Request request) {
  return Response.ok('Hello, Dart backend!');
}

Request in, Response out. That's the entire contract. Every endpoint you write is a handler. Every piece of middleware is a function that takes a handler and returns a handler.

Handlers can be async:

Future<Response> getUserHandler(Request request) async {
  final users = await userRepository.findAll();
  return Response.ok(jsonEncode(users));
}

Request and Response

Request gives you everything about the incoming HTTP call:

Future<Response> handler(Request request) async {
  // URL and path
  print(request.url);           // the full URL
  print(request.url.path);      // just the path

  // Path parameters (when using shelf_router)
  final id = request.params['id'];

  // Query parameters
  final page = request.url.queryParameters['page'];

  // Headers
  final auth = request.headers['authorization'];

  // Body
  final body = await request.readAsString();
  final json = jsonDecode(body) as Map<String, dynamic>;

  return Response.ok('handled');
}

Response has named constructors for common status codes:

Response.ok(body)           // 200
Response.notFound(body)     // 404
Response(201, body: body)   // any status code
Response(400, body: body)   // bad request
Response(401, body: body)   // unauthorized
Response(500, body: body)   // server error

Always set the Content-Type header when returning JSON:

Response.ok(
  jsonEncode({'message': 'success'}),
  headers: {'Content-Type': 'application/json'},
)

Router

shelf_router maps URL patterns and HTTP methods to handlers:

import 'package:shelf_router/shelf_router.dart';

final router = Router();

router.get('/users', getAllUsersHandler);
router.get('/users/<id>', getUserHandler);
router.post('/users', createUserHandler);
router.put('/users/<id>', updateUserHandler);
router.delete('/users/<id>', deleteUserHandler);

The syntax defines a path parameter. Access it inside the handler via request.params['id'].

Pipeline and Middleware

A Pipeline chains middleware together with a handler at the end:

import 'package:shelf/shelf.dart';

final handler = Pipeline()
    .addMiddleware(loggerMiddleware())
    .addMiddleware(errorMiddleware())
    .addMiddleware(authMiddleware())
    .addHandler(router.call);

Middleware is a function with this signature:

Middleware myMiddleware() {
  return (Handler innerHandler) {
    return (Request request) async {
      // Before the handler runs
      print('Request received: \({request.method} \){request.url}');

      final response = await innerHandler(request);

      // After the handler runs
      print('Response sent: ${response.statusCode}');

      return response;
    };
  };
}

The outer function returns a Middleware. That Middleware is a function that takes the next Handler in the chain and returns a new Handler. This nesting is what allows middleware to run code both before and after the inner handler.

Connecting to PostgreSQL

The Database Connection Manager

Create lib/config/database.dart:

import 'package:postgres/postgres.dart';
import 'env.dart';

class Database {
  static Connection? _connection;

  static Future<Connection> get connection async {
    if (_connection != null) return _connection!;
    _connection = await _connect();
    return _connection!;
  }

  static Future<Connection> _connect() async {
    final conn = await Connection.open(
      Endpoint(
        host: Env.dbHost,
        port: Env.dbPort,
        database: Env.dbName,
        username: Env.dbUser,
        password: Env.dbPassword,
      ),
      settings: const ConnectionSettings(
        sslMode: SslMode.disable,
      ),
    );

    print('✅ Database connected: \({Env.dbHost}:\){Env.dbPort}/${Env.dbName}');
    return conn;
  }

  static Future<void> close() async {
    await _connection?.close();
    _connection = null;
  }
}

This is a singleton connection manager – the same pattern Flutter engineers use for shared services. The connection is created once on first access and reused for every subsequent database call.

Running Migrations

Create the migrations folder and SQL files:

migrations/001_create_users.sql:

CREATE TABLE IF NOT EXISTS users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  first_name VARCHAR(100) NOT NULL,
  last_name VARCHAR(100) NOT NULL,
  is_active BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);

migrations/002_create_profiles.sql:

CREATE TABLE IF NOT EXISTS profiles (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  bio TEXT,
  avatar_url VARCHAR(500),
  phone VARCHAR(20),
  location VARCHAR(255),
  website VARCHAR(500),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  UNIQUE(user_id)
);

CREATE INDEX IF NOT EXISTS idx_profiles_user_id ON profiles(user_id);

Create a migration runner in lib/config/database.dart:

static Future<void> runMigrations() async {
  final conn = await connection;
  final migrationsDir = Directory('migrations');

  final files = migrationsDir
      .listSync()
      .whereType<File>()
      .where((f) => f.path.endsWith('.sql'))
      .toList()
    ..sort((a, b) => a.path.compareTo(b.path));

  for (final file in files) {
    final sql = await file.readAsString();
    await conn.execute(sql);
    print('✅ Migration applied: ${file.path}');
  }
}

Building the API

With the database connected and migrations in place, we can now build the actual API layer.

This section covers the models, repositories, and handlers for both users and profiles. Models define the shape of the data, repositories handle all database interactions, and handlers translate HTTP requests into repository calls and send responses back to the client. We'll build the user layer first, then the profile layer on top of it.

The User Model

The User model represents a single user record in the database. It maps directly to the users table created in the migration and handles two-way conversion between database rows and Dart objects.

Create lib/models/user.dart:

class User {
  final String id;
  final String email;
  final String passwordHash;
  final String firstName;
  final String lastName;
  final bool isActive;
  final DateTime createdAt;
  final DateTime updatedAt;

  const User({
    required this.id,
    required this.email,
    required this.passwordHash,
    required this.firstName,
    required this.lastName,
    required this.isActive,
    required this.createdAt,
    required this.updatedAt,
  });

  factory User.fromRow(Map<String, dynamic> row) => User(
        id: row['id'] as String,
        email: row['email'] as String,
        passwordHash: row['password_hash'] as String,
        firstName: row['first_name'] as String,
        lastName: row['last_name'] as String,
        isActive: row['is_active'] as bool,
        createdAt: row['created_at'] as DateTime,
        updatedAt: row['updated_at'] as DateTime,
      );

  // Never include passwordHash in JSON responses
  Map<String, dynamic> toJson() => {
        'id': id,
        'email': email,
        'firstName': firstName,
        'lastName': lastName,
        'isActive': isActive,
        'createdAt': createdAt.toIso8601String(),
        'updatedAt': updatedAt.toIso8601String(),
      };
}

fromRow maps a PostgreSQL result row to a User. toJson deliberately excludes passwordHash – you should never return password data in API responses.

The User Repository

The UserRepository is the single point of contact between the application and the users table. Every database operation for users goes through here, keeping the SQL contained and the handlers clean.

Create lib/repositories/user_repository.dart:

import 'dart:async';
import 'package:postgres/postgres.dart';
import '../config/database.dart';
import '../models/user.dart';

class UserRepository {
  Future<Connection> get _conn => Database.connection;

  Future<List<User>> findAll() async {
    final conn = await _conn;
    final results = await conn.execute(
      'SELECT * FROM users WHERE is_active = TRUE ORDER BY created_at DESC',
    );

    return results.map((row) => User.fromRow(row.toColumnMap())).toList();
  }

  Future<User?> findById(String id) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('SELECT * FROM users WHERE id = @id AND is_active = TRUE'),
      parameters: {'id': id},
    );

    if (results.isEmpty) return null;
    return User.fromRow(results.first.toColumnMap());
  }

  Future<User?> findByEmail(String email) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('SELECT * FROM users WHERE email = @email'),
      parameters: {'email': email},
    );

    if (results.isEmpty) return null;
    return User.fromRow(results.first.toColumnMap());
  }

  Future<User> create({
    required String email,
    required String passwordHash,
    required String firstName,
    required String lastName,
  }) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('''
        INSERT INTO users (email, password_hash, first_name, last_name)
        VALUES (@email, @passwordHash, @firstName, @lastName)
        RETURNING *
      '''),
      parameters: {
        'email': email,
        'passwordHash': passwordHash,
        'firstName': firstName,
        'lastName': lastName,
      },
    );

    return User.fromRow(results.first.toColumnMap());
  }

  Future<User?> update({
    required String id,
    String? firstName,
    String? lastName,
  }) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('''
        UPDATE users
        SET
          first_name = COALESCE(@firstName, first_name),
          last_name  = COALESCE(@lastName, last_name),
          updated_at = NOW()
        WHERE id = @id AND is_active = TRUE
        RETURNING *
      '''),
      parameters: {
        'id': id,
        'firstName': firstName,
        'lastName': lastName,
      },
    );

    if (results.isEmpty) return null;
    return User.fromRow(results.first.toColumnMap());
  }

  Future<bool> delete(String id) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('''
        UPDATE users SET is_active = FALSE, updated_at = NOW()
        WHERE id = @id AND is_active = TRUE
        RETURNING id
      '''),
      parameters: {'id': id},
    );

    return results.isNotEmpty;
  }
}

A few things worth noting here. Sql.named uses named parameters (@paramName) instead of positional parameters. This prevents SQL injection and makes queries readable.

Also, the delete operation is a soft delete. It sets is_active = FALSE rather than removing the row. This is the standard production approach: data is never truly deleted, it's deactivated.

COALESCE(@firstName, first_name) on the update means: use the new value if provided, otherwise keep the existing value. This handles partial updates cleanly without requiring all fields every time.

User Handlers

The UserHandler class exposes the repository operations as HTTP endpoints. It owns a Router instance internally and maps each route to a private method, keeping the routing logic and the handler logic together in one place.

Create lib/handlers/user_handler.dart:

import 'dart:convert';
import 'package:shelf/shelf.dart';
import 'package:shelf_router/shelf_router.dart';
import '../repositories/user_repository.dart';

class UserHandler {
  final UserRepository _repository;

  UserHandler(this._repository);

  Router get router {
    final router = Router();
    router.get('/', _getAll);
    router.get('/<id>', _getOne);
    router.put('/<id>', _update);
    router.delete('/<id>', _delete);
    return router;
  }

  Future<Response> _getAll(Request request) async {
    final users = await _repository.findAll();
    return Response.ok(
      jsonEncode(users.map((u) => u.toJson()).toList()),
      headers: {'Content-Type': 'application/json'},
    );
  }

  Future<Response> _getOne(Request request, String id) async {
    final user = await _repository.findById(id);

    if (user == null) {
      return Response.notFound(
        jsonEncode({'error': 'User not found'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    return Response.ok(
      jsonEncode(user.toJson()),
      headers: {'Content-Type': 'application/json'},
    );
  }

  Future<Response> _update(Request request, String id) async {
    final body = jsonDecode(await request.readAsString()) as Map<String, dynamic>;

    final user = await _repository.update(
      id: id,
      firstName: body['firstName'] as String?,
      lastName: body['lastName'] as String?,
    );

    if (user == null) {
      return Response.notFound(
        jsonEncode({'error': 'User not found'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    return Response.ok(
      jsonEncode(user.toJson()),
      headers: {'Content-Type': 'application/json'},
    );
  }

  Future<Response> _delete(Request request, String id) async {
    final deleted = await _repository.delete(id);

    if (!deleted) {
      return Response.notFound(
        jsonEncode({'error': 'User not found'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    return Response(
      204,
      headers: {'Content-Type': 'application/json'},
    );
  }
}

The Profile Model

The Profile model represents a user's extended information, stored separately from the core user record. The one-to-one relationship is enforced by the unique index on user_id in the profiles table. All fields except userId are nullable since a profile can be created with partial information and filled in over time.

Create lib/models/profile.dart:

class Profile {
  final String id;
  final String userId;
  final String? bio;
  final String? avatarUrl;
  final String? phone;
  final String? location;
  final String? website;
  final DateTime createdAt;
  final DateTime updatedAt;

  const Profile({
    required this.id,
    required this.userId,
    this.bio,
    this.avatarUrl,
    this.phone,
    this.location,
    this.website,
    required this.createdAt,
    required this.updatedAt,
  });

  factory Profile.fromRow(Map<String, dynamic> row) => Profile(
        id: row['id'] as String,
        userId: row['user_id'] as String,
        bio: row['bio'] as String?,
        avatarUrl: row['avatar_url'] as String?,
        phone: row['phone'] as String?,
        location: row['location'] as String?,
        website: row['website'] as String?,
        createdAt: row['created_at'] as DateTime,
        updatedAt: row['updated_at'] as DateTime,
      );

  Map<String, dynamic> toJson() => {
        'id': id,
        'userId': userId,
        'bio': bio,
        'avatarUrl': avatarUrl,
        'phone': phone,
        'location': location,
        'website': website,
        'createdAt': createdAt.toIso8601String(),
        'updatedAt': updatedAt.toIso8601String(),
      };
}

The Profile Repository

The ProfileRepository handles all database operations for the profiles table. Unlike the user repository which looks up by id, most profile operations use userId as the lookup key since that is how the client references a profile — by whose it belongs to, not by its own internal ID.

Create lib/repositories/profile_repository.dart:

import 'package:postgres/postgres.dart';
import '../config/database.dart';
import '../models/profile.dart';

class ProfileRepository {
  Future<Connection> get _conn => Database.connection;

  Future<Profile?> findByUserId(String userId) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('SELECT * FROM profiles WHERE user_id = @userId'),
      parameters: {'userId': userId},
    );

    if (results.isEmpty) return null;
    return Profile.fromRow(results.first.toColumnMap());
  }

  Future<Profile> create({
    required String userId,
    String? bio,
    String? avatarUrl,
    String? phone,
    String? location,
    String? website,
  }) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('''
        INSERT INTO profiles (user_id, bio, avatar_url, phone, location, website)
        VALUES (@userId, @bio, @avatarUrl, @phone, @location, @website)
        RETURNING *
      '''),
      parameters: {
        'userId': userId,
        'bio': bio,
        'avatarUrl': avatarUrl,
        'phone': phone,
        'location': location,
        'website': website,
      },
    );

    return Profile.fromRow(results.first.toColumnMap());
  }

  Future<Profile?> update({
    required String userId,
    String? bio,
    String? avatarUrl,
    String? phone,
    String? location,
    String? website,
  }) async {
    final conn = await _conn;
    final results = await conn.execute(
      Sql.named('''
        UPDATE profiles
        SET
          bio        = COALESCE(@bio, bio),
          avatar_url = COALESCE(@avatarUrl, avatar_url),
          phone      = COALESCE(@phone, phone),
          location   = COALESCE(@location, location),
          website    = COALESCE(@website, website),
          updated_at = NOW()
        WHERE user_id = @userId
        RETURNING *
      '''),
      parameters: {
        'userId': userId,
        'bio': bio,
        'avatarUrl': avatarUrl,
        'phone': phone,
        'location': location,
        'website': website,
      },
    );

    if (results.isEmpty) return null;
    return Profile.fromRow(results.first.toColumnMap());
  }
}

Profile Handlers

The ProfileHandler manages the profile endpoints nested under a user's ID. Before every operation, it verifies the parent user exists — a profile can't be created, fetched, or updated for a user that doesn't exist. It also prevents duplicate profiles by checking for an existing record before allowing a create.

Create lib/handlers/profile_handler.dart:

import 'dart:convert';
import 'package:shelf/shelf.dart';
import 'package:shelf_router/shelf_router.dart';
import '../repositories/profile_repository.dart';
import '../repositories/user_repository.dart';

class ProfileHandler {
  final ProfileRepository _profileRepository;
  final UserRepository _userRepository;

  ProfileHandler(this._profileRepository, this._userRepository);

  Router get router {
    final router = Router();
    router.get('/<userId>/profile', _getProfile);
    router.post('/<userId>/profile', _createProfile);
    router.put('/<userId>/profile', _updateProfile);
    return router;
  }

  Future<Response> _getProfile(Request request, String userId) async {
    final user = await _userRepository.findById(userId);
    if (user == null) {
      return Response.notFound(
        jsonEncode({'error': 'User not found'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    final profile = await _profileRepository.findByUserId(userId);
    if (profile == null) {
      return Response.notFound(
        jsonEncode({'error': 'Profile not found'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    return Response.ok(
      jsonEncode(profile.toJson()),
      headers: {'Content-Type': 'application/json'},
    );
  }

  Future<Response> _createProfile(Request request, String userId) async {
    final user = await _userRepository.findById(userId);
    if (user == null) {
      return Response.notFound(
        jsonEncode({'error': 'User not found'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    final existing = await _profileRepository.findByUserId(userId);
    if (existing != null) {
      return Response(
        409,
        body: jsonEncode({'error': 'Profile already exists for this user'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    final body = jsonDecode(await request.readAsString()) as Map<String, dynamic>;

    final profile = await _profileRepository.create(
      userId: userId,
      bio: body['bio'] as String?,
      avatarUrl: body['avatarUrl'] as String?,
      phone: body['phone'] as String?,
      location: body['location'] as String?,
      website: body['website'] as String?,
    );

    return Response(
      201,
      body: jsonEncode(profile.toJson()),
      headers: {'Content-Type': 'application/json'},
    );
  }

  Future<Response> _updateProfile(Request request, String userId) async {
    final body = jsonDecode(await request.readAsString()) as Map<String, dynamic>;

    final profile = await _profileRepository.update(
      userId: userId,
      bio: body['bio'] as String?,
      avatarUrl: body['avatarUrl'] as String?,
      phone: body['phone'] as String?,
      location: body['location'] as String?,
      website: body['website'] as String?,
    );

    if (profile == null) {
      return Response.notFound(
        jsonEncode({'error': 'Profile not found'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    return Response.ok(
      jsonEncode(profile.toJson()),
      headers: {'Content-Type': 'application/json'},
    );
  }
}

Authentication

With the core user and profile CRUD in place, the next step is securing the API.

Authentication in this project works in two parts: an AuthService handles the cryptographic operations — password hashing and JWT generation and verification — and an AuthHandler exposes the register and login endpoints that clients call to get a token. Once a token is issued, the AuthMiddleware validates it on every protected request before it reaches a handler.

Password Hashing

Create lib/services/auth_service.dart:

import 'package:bcrypt/bcrypt.dart';
import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
import '../config/env.dart';
import '../models/user.dart';

class AuthService {
  String hashPassword(String password) {
    return BCrypt.hashpw(password, BCrypt.gensalt());
  }

  bool verifyPassword(String password, String hash) {
    return BCrypt.checkpw(password, hash);
  }

  String generateToken(User user) {
    final jwt = JWT(
      {
        'sub': user.id,
        'email': user.email,
        'iat': DateTime.now().millisecondsSinceEpoch ~/ 1000,
      },
    );

    return jwt.sign(
      SecretKey(Env.jwtSecret),
      expiresIn: Duration(hours: Env.jwtExpiryHours),
    );
  }

  JWT? verifyToken(String token) {
    try {
      return JWT.verify(token, SecretKey(Env.jwtSecret));
    } catch (_) {
      return null;
    }
  }
}

BCrypt.hashpw generates a salted hash. BCrypt.checkpw verifies a plain password against a stored hash. The salt is embedded in the hash itself – you don't store it separately.

verifyToken returns null on any failure, expired token, invalid signature, or malformed token rather than throwing. This keeps the auth middleware clean.

Auth Handlers

Create lib/handlers/auth_handler.dart:

import 'dart:convert';
import 'package:shelf/shelf.dart';
import 'package:shelf_router/shelf_router.dart';
import '../repositories/user_repository.dart';
import '../services/auth_service.dart';

class AuthHandler {
  final UserRepository _userRepository;
  final AuthService _authService;

  AuthHandler(this._userRepository, this._authService);

  Router get router {
    final router = Router();
    router.post('/register', _register);
    router.post('/login', _login);
    return router;
  }

  Future<Response> _register(Request request) async {
    final body = jsonDecode(await request.readAsString()) as Map<String, dynamic>;

    final email = body['email'] as String?;
    final password = body['password'] as String?;
    final firstName = body['firstName'] as String?;
    final lastName = body['lastName'] as String?;

    if (email == null || password == null || firstName == null || lastName == null) {
      return Response(
        400,
        body: jsonEncode({'error': 'email, password, firstName, and lastName are required'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    if (password.length < 8) {
      return Response(
        400,
        body: jsonEncode({'error': 'Password must be at least 8 characters'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    final existing = await _userRepository.findByEmail(email);
    if (existing != null) {
      return Response(
        409,
        body: jsonEncode({'error': 'An account with this email already exists'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    final passwordHash = _authService.hashPassword(password);

    final user = await _userRepository.create(
      email: email,
      passwordHash: passwordHash,
      firstName: firstName,
      lastName: lastName,
    );

    final token = _authService.generateToken(user);

    return Response(
      201,
      body: jsonEncode({
        'user': user.toJson(),
        'token': token,
      }),
      headers: {'Content-Type': 'application/json'},
    );
  }

  Future<Response> _login(Request request) async {
    final body = jsonDecode(await request.readAsString()) as Map<String, dynamic>;

    final email = body['email'] as String?;
    final password = body['password'] as String?;

    if (email == null || password == null) {
      return Response(
        400,
        body: jsonEncode({'error': 'email and password are required'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    final user = await _userRepository.findByEmail(email);

    // Deliberately vague error, never confirm whether an email exists
    if (user == null || !_authService.verifyPassword(password, user.passwordHash)) {
      return Response(
        401,
        body: jsonEncode({'error': 'Invalid email or password'}),
        headers: {'Content-Type': 'application/json'},
      );
    }

    final token = _authService.generateToken(user);

    return Response.ok(
      jsonEncode({
        'user': user.toJson(),
        'token': token,
      }),
      headers: {'Content-Type': 'application/json'},
    );
  }
}

The login error message is deliberately vague: "Invalid email or password" rather than "Email not found" or "Wrong password." Confirming which part is wrong helps attackers enumerate valid accounts.

Auth Middleware

Create lib/middleware/auth_middleware.dart:

import 'dart:convert';
import 'package:shelf/shelf.dart';
import '../services/auth_service.dart';

Middleware authMiddleware(AuthService authService) {
  return (Handler innerHandler) {
    return (Request request) async {
      final authHeader = request.headers['authorization'];

      if (authHeader == null || !authHeader.startsWith('Bearer ')) {
        return Response(
          401,
          body: jsonEncode({'error': 'Authorization header missing or malformed'}),
          headers: {'Content-Type': 'application/json'},
        );
      }

      final token = authHeader.substring(7); // Remove 'Bearer '
      final jwt = authService.verifyToken(token);

      if (jwt == null) {
        return Response(
          401,
          body: jsonEncode({'error': 'Invalid or expired token'}),
          headers: {'Content-Type': 'application/json'},
        );
      }

      // Attach the user ID to the request context for downstream handlers
      final updatedRequest = request.change(
        context: {
          ...request.context,
          'userId': jwt.payload['sub'] as String,
          'userEmail': jwt.payload['email'] as String,
        },
      );

      return innerHandler(updatedRequest);
    };
  };
}

request.change(context: {...}) is how Shelf passes data from middleware to handlers, the equivalent of attaching data to a request in Express or ASP.NET middleware. Any handler downstream can read request.context['userId'] to know which user is authenticated.

Error Handling

No matter how carefully you write your handlers, unexpected failures will happen in production — malformed request bodies, database timeouts, unhandled edge cases.

Rather than letting each handler manage its own error responses individually, we'll centralise error handling in a single middleware that wraps the entire pipeline. This guarantees a consistent error response shape across every endpoint and prevents internal error details from leaking to the client.

Create lib/middleware/error_middleware.dart:

import 'dart:convert';
import 'package:shelf/shelf.dart';

Middleware errorMiddleware() {
  return (Handler innerHandler) {
    return (Request request) async {
      try {
        return await innerHandler(request);
      } on FormatException catch (e) {
        return Response(
          400,
          body: jsonEncode({'error': 'Invalid request body: ${e.message}'}),
          headers: {'Content-Type': 'application/json'},
        );
      } catch (e, stackTrace) {
        // Log the full error and stack trace server-side
        print('Unhandled error: $e');
        print(stackTrace);

        // Never expose internal error details to the client
        return Response(
          500,
          body: jsonEncode({'error': 'An internal server error occurred'}),
          headers: {'Content-Type': 'application/json'},
        );
      }
    };
  };
}

Create lib/middleware/logger_middleware.dart:

import 'package:shelf/shelf.dart';

Middleware loggerMiddleware() {
  return (Handler innerHandler) {
    return (Request request) async {
      final start = DateTime.now();

      final response = await innerHandler(request);

      final duration = DateTime.now().difference(start).inMilliseconds;
      print(
        '[${DateTime.now().toIso8601String()}] '
        '\({request.method} \){request.url.path} '
        '→ \({response.statusCode} (\){duration}ms)',
      );

      return response;
    };
  };
}

Wiring Everything Together

With the handlers, repositories, and middleware all in place, the final step is connecting them into a single running server. The router maps URL prefixes to their handler, the pipeline stacks the middleware in the correct order, and the entry point boots everything up in sequence — loading environment variables, running migrations, and starting the server.

Create lib/router.dart:

import 'package:shelf_router/shelf_router.dart';
import 'handlers/auth_handler.dart';
import 'handlers/user_handler.dart';
import 'handlers/profile_handler.dart';
import 'middleware/auth_middleware.dart';
import 'repositories/user_repository.dart';
import 'repositories/profile_repository.dart';
import 'services/auth_service.dart';

Router createRouter() {
  final userRepository = UserRepository();
  final profileRepository = ProfileRepository();
  final authService = AuthService();

  final authHandler = AuthHandler(userRepository, authService);
  final userHandler = UserHandler(userRepository);
  final profileHandler = ProfileHandler(profileRepository, userRepository);

  final router = Router();

  // Public routes, no auth required
  router.mount('/auth', authHandler.router.call);

  // Protected routes, auth middleware applied
  router.mount(
    '/users',
    Pipeline()
        .addMiddleware(authMiddleware(authService))
        .addHandler(userHandler.router.call),
  );

  router.mount(
    '/users',
    Pipeline()
        .addMiddleware(authMiddleware(authService))
        .addHandler(profileHandler.router.call),
  );

  return router;
}

Create the entry point bin/server.dart:

import 'dart:io';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as shelf_io;
import '../lib/config/database.dart';
import '../lib/config/env.dart';
import '../lib/middleware/error_middleware.dart';
import '../lib/middleware/logger_middleware.dart';
import '../lib/router.dart';

void main() async {
  // Load environment variables
  Env.load();

  // Run database migrations
  await Database.runMigrations();

  // Build the handler pipeline
  final router = createRouter();

  final handler = Pipeline()
      .addMiddleware(errorMiddleware())
      .addMiddleware(loggerMiddleware())
      .addHandler(router.call);

  // Start the server
  final server = await shelf_io.serve(
    handler,
    InternetAddress.anyIPv4,
    Env.port,
  );

  print('🚀 Server running on port ${server.port}');
}

Run the server:

dart run bin/server.dart
# ✅ Database connected: localhost:5432/user_profile_api
# ✅ Migration applied: migrations/001_create_users.sql
# ✅ Migration applied: migrations/002_create_profiles.sql
# 🚀 Server running on port 8080

Deployment

The server is running locally and all endpoints are working. Now it's time to ship it.

We'll cover two deployment paths: first packaging the app and database together with Docker Compose for local production testing, then deploying to Fly.io where your API will be accessible over the internet with a managed PostgreSQL database and automatic TLS.

Dockerfile

Create Dockerfile in the project root:

FROM dart:stable AS build

WORKDIR /app
COPY pubspec.* ./
RUN dart pub get

COPY . .
RUN dart compile exe bin/server.dart -o bin/server

FROM debian:stable-slim

RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/bin/server bin/server
COPY --from=build /app/migrations migrations/

EXPOSE 8080

CMD ["bin/server"]

This is a multi-stage build. The first stage uses the full Dart SDK image to compile the server to a native binary. The second stage copies only the compiled binary and migrations into a minimal Debian image – no Dart SDK, no source code, no build tools. The final image is lean and production-ready.

Docker Compose for Local Production Testing

Update docker-compose.yml to include the app alongside the database:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: user_profile_db
    environment:
      POSTGRES_DB: user_profile_api
      POSTGRES_USER: dart_user
      POSTGRES_PASSWORD: dart_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dart_user -d user_profile_api"]
      interval: 5s
      timeout: 5s
      retries: 5

  api:
    build: .
    container_name: user_profile_api
    ports:
      - "8080:8080"
    environment:
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: user_profile_api
      DB_USER: dart_user
      DB_PASSWORD: dart_password
      JWT_SECRET: local_test_secret_replace_in_production
      JWT_EXPIRY_HOURS: 24
      PORT: 8080
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

The healthcheck on the Postgres service ensures that the API container only starts once the database is ready to accept connections (a common production problem when services start simultaneously).

Build and run everything:

docker compose up --build

Deploying to Fly.io

Fly.io is one of the cleanest deployment targets for containerized backend services. It handles global distribution, automatic TLS, and managed PostgreSQL databases.

Step 1 – Install and authenticate:

# macOS
brew install flyctl

# Authenticate
fly auth login

Step 2 – Launch the app:

fly launch

Fly detects the Dockerfile automatically and asks a few questions: app name, region, and whether to create a PostgreSQL database. Answer yes to the PostgreSQL prompt, and Fly will provision a managed database and inject the connection string automatically.

Step 3 – Set environment variables:

fly secrets set JWT_SECRET="your_production_secret_here"
fly secrets set JWT_EXPIRY_HOURS="24"

Database connection variables are set automatically by Fly when it provisions the PostgreSQL cluster.

Step 4 – Deploy:

fly deploy

Fly builds the Docker image, pushes it to their registry, and deploys it to your chosen region. Once complete:

fly status
# Your app is running at https://your-app-name.fly.dev

Step 5 – Verify the deployment:

curl https://your-app-name.fly.dev/auth/register \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123","firstName":"Seyi","lastName":"Dev"}'

Testing the API

With the server running locally on port 8080, here's the full flow to verify that everything works end to end.

Register a user:

curl http://localhost:8080/auth/register \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seyi@example.com",
    "password": "securepassword",
    "firstName": "Seyi",
    "lastName": "Dev"
  }'

Response:

{
  "user": {
    "id": "uuid-here",
    "email": "seyi@example.com",
    "firstName": "Seyi",
    "lastName": "Dev",
    "isActive": true,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  },
  "token": "eyJhbGci..."
}

Login:

curl http://localhost:8080/auth/login \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "seyi@example.com", "password": "securepassword"}'

Get all users (authenticated):

curl http://localhost:8080/users \
  -H "Authorization: Bearer eyJhbGci..."

Create a profile:

curl http://localhost:8080/users/{userId}/profile \
  -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "bio": "Flutter engineer turned backend developer",
    "location": "Lagos, Nigeria",
    "website": "https://example.com"
  }'

Update a user:

curl http://localhost:8080/users/{userId} \
  -X PUT \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"firstName": "Oluwaseyi"}'

Delete a user:

curl http://localhost:8080/users/{userId} \
  -X DELETE \
  -H "Authorization: Bearer eyJhbGci..."

Conclusion

You just built and deployed a production-grade REST API in Dart – the same language you already know from Flutter. No new language, no new paradigm. Just Dart running in a different context.

The Shelf mental model (Handlers, Middleware, Pipelines, Routers) is deliberately minimal. It doesn't make decisions for you. It gives you composable primitives and lets you assemble them into exactly the architecture your project needs. That philosophy will feel familiar to Flutter engineers who build their own clean architecture rather than relying on a prescriptive framework.

What you built here – models, repositories, services, handlers, and middleware – is the same separation of concerns you apply in Flutter, applied to the backend. The concepts transfer. The Dart skills transfer. The architecture discipline transfers.

With this, you'll understand that Dart is a powerful language that cuts across both frontend and backend ecosystems. Aside from Shelf, we have Dartfrog and Serverpod which still functions well on the backend side of things. More on those in upcoming articles.

So yeah, try this out and thank me later!

Roadmaps talk about velocity. Leadership meetings talk about reducing cycle time. Quarterly goals talk about faster execution and quicker releases.

Every business wants teams moving faster.

Then many of those same companies make a decision that quietly slows everything down. They optimise for infrastructure flexibility instead of product delivery.

It sounds reasonable in the beginning. Teams want control. Engineers want options. Platform architects want systems that can support every future scenario.

So production teams start building infrastructure ecosystems around themselves.

Deployment pipelines get built from scratch. Cloud resources become heavily customised. Internal platforms gain endless knobs, switches, and configuration layers. New projects begin with architecture discussions instead of customer problems.

Months later, software delivery slows down.

Product teams miss timelines. Releases move out by quarters. Customer feedback arrives later. Competitors keep shipping.

The tradeoff hiding underneath all of this is simple. Teams choose flexibility over actually shipping.

And beyond a certain point, flexibility becomes one of the most expensive forms of organisational drag a company can create.

What We'll Cover:

• The Myth That More Flexibility Creates Better Production Systems

• Infrastructure Ownership Quietly Becomes a Second Business

• The Real Cost Is Delayed Customer Learning

• PaaS Changes the Optimisation Function

• The Best Production Teams Remove Decisions

• Custom Infrastructure Usually Solves Problems Nobody Has Yet

• The Real Competitive Advantage Is Shipping Faster

• When PaaS Might Not Be the Right Choice

• Stop Building Infrastructure Businesses By Accident

The Myth That More Flexibility Creates Better Production Systems

Engineering teams love optionality. The logic sounds convincing.

If infrastructure is fully customizable, teams can adapt to future requirements. If deployment systems are built internally, every use case can be supported. If every layer is configurable, engineers can optimise for unique situations.

This feels like responsible engineering. But it often becomes expensive business behaviour.

Most production teams massively overestimate how often they need deep infrastructure flexibility.

What actually happens becomes predictable.

A product team starts a new initiative. Instead of shipping an early version and learning from customers, discussions begin.

• Should Kubernetes clusters be organised by team or service?

• Should CI/CD use GitHub Actions or Jenkins?

• Should secrets management use Vault or cloud-native tooling?

• Should observability use Prometheus or Datadog?

• Should deployment strategies use canary releases, blue-green deployments, or something custom?

Weeks disappear. No customer sees anything. No assumptions get tested. No learning happens.

Meanwhile, product managers wait. Leadership waits. Customers wait.

Even with agentic coding tools like Claude generating code, scaffolding systems and accelerating implementation, teams still lose speed when every output collides with infrastructure decisions and deployment debates.

The problem isn't technology. The problem is optimising around theoretical future flexibility instead of present business outcomes.

Software creates value when customers use it. Everything else is support work.

Infrastructure Ownership Quietly Becomes a Second Business

Traditional deployment models accidentally create a dangerous pattern: companies think they are building products. Slowly, they start building infrastructure organisations.

Production teams provision servers. Then networking. Then IAM systems. Then deployment pipelines. Then, observability layers. Then secrets management. Then autoscaling. Then rollback systems.

Every decision feels reasonable in isolation. But collectively, teams create an operational machine they now own forever.

And ownership is where the hidden cost appears.

Because infrastructure work doesn't end after launch. It expands. Pipelines need maintenance. Security policies change. Monitoring systems require tuning. Platform dependencies break. Internal tooling needs upgrades.

Production teams gradually spend more time maintaining systems around software than improving software itself.

This creates a strange situation: highly paid engineers become caretakers for infrastructure instead of builders of customer value.

No customer purchases a product because deployment pipelines have become elegant. No customer upgrades because IAM policies are beautifully designed. No competitor loses market share because Kubernetes YAML looks sophisticated.

Customers care about products solving problems. Infrastructure only matters when it slows product delivery.

And infrastructure ownership creates endless opportunities for that to happen.

The Real Cost Is Delayed Customer Learning

The biggest cost of infrastructure complexity isn't engineering effort. It's delayed learning.

Software companies win through feedback loops. Teams ship something. Customers react. Teams learn. Products improve.

The faster this cycle operates, the stronger the company becomes.

Infrastructure work interrupts that loop. Every month spent building deployment systems is a month where customers aren't using new features. Every quarter spent designing internal platforms delays customer feedback. Every architecture discussion delays real market signals.

This is where many organisations misunderstand velocity.

They look at sprint metrics. They measure tickets completed. They count engineering output.

But business speed isn't measured through internal activity. Business speed measures how quickly ideas become customer reality.

Infrastructure ownership slows that process dramatically. And slower learning creates slower companies.

PaaS Changes the Optimisation Function

This is where Platform as a Service changes the equation.

PaaS forces organisations to optimise around shipping rather than infrastructure ownership. That shift matters more than most teams realise.

Instead of spending weeks designing deployment architecture, production teams connect repositories and deploy.

Instead of building pipelines manually, pipelines already exist.

Instead of designing scaling systems, scaling becomes infrastructure behaviour rather than engineering work.

Instead of repeatedly building foundations, infrastructure becomes a utility.

That sounds simple. It should be simple. Deployment should feel boring. But the fact that deployment often becomes a major organisational project is usually evidence of unnecessary complexity rather than unavoidable complexity.

PaaS providers remove entire categories of decisions. And while many engineers see that as a compromise, it's often the opposite.

Constraints create speed. Speed creates learning. Learning creates better products.

The Best Production Teams Remove Decisions

There's a common misconception that elite engineering organisations maximise options. The opposite is often true.

High-performing production teams aggressively eliminate decisions. They standardise. They create defaults. They remove unnecessary choices.

Because every decision carries a cost.

Cognitive load grows. Coordination increases. Meetings multiply. Dependencies expand. Eventually, the workaround software becomes larger than the software itself.

PaaS systems follow a different philosophy. They intentionally reduce optionality.

That reduction creates focus. And focus creates product velocity. Product velocity creates business outcomes.

The chain is straightforward. Too many organisations break it by introducing infrastructure ownership far too early.

Custom Infrastructure Usually Solves Problems Nobody Has Yet

One of the most expensive habits in software companies is solving future problems before current ones exist.

Teams build for scale before scale exists. They create multi-region architectures before international users arrive. They build deployment frameworks before deployment pain appears.

This usually comes from good intentions. Engineers want to avoid future rewrites. But the irony is that premature flexibility creates an immediate business slowdown.

A startup with twenty engineers shouldn't operate like a company with ten thousand engineers. Yet many production teams copy infrastructure patterns from giant technology firms.

What gets ignored is context. Large technology companies have entire platform teams maintaining internal systems. They have thousands of engineers supporting infrastructure investments.

Most companies do not.

Copying technical architecture without copying organisational scale creates enormous inefficiency.

PaaS acts as protection against this behaviour. It prevents teams from accidentally becoming infrastructure companies before they become successful product companies.

The Real Competitive Advantage Is Shipping Faster

Companies rarely lose because infrastructure flexibility was insufficient. They lost because competitors learned faster.

Speed matters. Not speed in sprint or linear dashboards. Not speed in story points.

Actual speed. The ability to move ideas into production quickly. The ability to test assumptions rapidly. The ability to learn continuously.

Shipping creates learning. Learning creates improvement. Improvement creates advantage.

Infrastructure complexity interrupts this loop. PaaS strengthens it.

This is why deployment decisions should never be treated as purely technical discussions. They are business decisions.

Infrastructure ownership affects company velocity. Velocity affects market outcomes.

The argument isn't about servers. The argument is about competitive speed.

When PaaS Might Not Be the Right Choice

There are situations where PaaS can become limiting.

Organisations with highly specialised infrastructure requirements may require direct control over networking, security layers, hardware optimisation, or deployment behaviour.

Some industries have regulatory requirements that create unusually specific infrastructure needs.

Large organisations with mature platform engineering teams may also justify custom infrastructure investments.

There are also cases where platform costs become meaningful at very large scale.

These scenarios exist. But many companies use edge cases as justification years before they become relevant. They prepare for infrastructure problems they may never have while struggling to ship ordinary product releases today.

That sequence creates unnecessary friction.

Stop Building Infrastructure Businesses By Accident

Engineering culture often celebrates flexibility.

Flexibility sounds sophisticated. It sounds future-proof. It sounds like good systems thinking.

But flexibility carries a cost. Every additional option creates complexity. Every additional decision slows movement. Every additional layer creates maintenance work.

Production teams should ask a simpler question. Does this help us ship customer-facing software faster? If the answer is no, it deserves scrutiny.

Too many companies accidentally build infrastructure ecosystems that optimise for hypothetical future needs.

Meanwhile, competitors deploy products, learn from customers and improve faster.

Shipping beats flexibility. And for many production teams, choosing a PaaS is one of the clearest ways to prove it.

Hope you enjoyed this article. You can connect with me on LinkedIn.

try {
  final user = await repository.getUser(id);
  // do something with user
} catch (e) {
  // what is e? who knows.
  print(e.toString());
}

It works. It compiles. It ships. And then six months later, a bug report lands in your inbox from a user who got a blank screen instead of an error message, and you spend three hours tracing it back to a catch (e) block that swallowed the failure silently.

This is the fundamental problem with exception-based error handling in Dart. Exceptions are invisible in function signatures. They carry no type information at the call site. The compiler can't help you because it doesn't know a function can fail.

Every failure path is a social contract between the author and the caller — and social contracts break under pressure, in large teams, and at 2am during an incident.

Production applications deserve better than that.

In this article, we're going to walk through a complete, modern approach to error handling in Dart — the kind used in real production Flutter codebases. We'll start with Dart Records as lightweight result containers, build a proper sealed Result type, extend it into the Monad pattern, integrate the dartz package for functional Either types, and finally cap it off with typed, exhaustive exceptions using Freezed.

By the end, failures in your codebase will be typed, visible, compiler-enforced, and impossible to ignore.

Table of Contents

• Prerequisites

• The Problem with Exceptions in Dart

• Part 1: Record Types as Lightweight Result Containers

  • What are Dart Records?

  • Records as Result Types

  • Sealed Classes as Namespaced Constructors

  • Domain-Specific Record Types

• Part 2: Building a Proper Sealed Result Type

  • The AppResult Sealed Class

  • Consuming Results with when()

  • Why This is Better

• Part 3: Extending to the Monad Pattern

  • What Makes Something a Monad?

  • Adding map and flatMap

  • Chaining Operations

• Part 4: Either with dartz

  • What is Either?

  • Using Either in Practice

  • Bridging Records and Either

  • Folding an Either

• Part 5: Typed Exceptions with Freezed

  • Why Freezed for Exceptions?

  • Building iException

  • Pattern Matching on Exception Types

  • A Cleaner Base Getter Pattern

• Part 6: Putting It All Together

  • The Full Architecture

  • Repository Layer

  • Domain Layer

  • Presentation Layer

• Conclusion

Prerequisites

Before starting, you should have:

• A working Flutter project with Dart 3.0 or later

• Basic familiarity with Dart generics and async/await

• Basic understanding of sealed classes in Dart

• The freezed, freezed_annotation, and build_runner packages available

• The dartz package available

• flutter pub run build_runner build working in your project

The Problem with Exceptions in Dart

Let's look at what typical exception-based error handling actually looks like across a full stack:

// Repository
Future<User> getUser(String id) async {
  final response = await dio.get('/users/$id');
  return User.fromJson(response.data);
}

// Use case
Future<User> execute(String id) async {
  return await repository.getUser(id);
}

// ViewModel
Future<void> loadUser(String id) async {
  try {
    final user = await useCase.execute(id);
    state = UserState.loaded(user);
  } catch (e) {
    state = UserState.error(e.toString());
  }
}

This looks reasonable. But there are serious hidden problems here.

The failure is invisible in the signature: Future<User> tells the caller "you will get a User." It says nothing about what happens when the network fails, when the token expires, or when the JSON is malformed. The caller has to know — by reading the implementation — that this function can fail.

The compiler can't help you: If you forget the try/catch in the ViewModel, the app compiles fine. The crash happens at runtime, in production, in front of a real user.

catch (e) catches everything: A typo in a variable name, a null dereference, a real network failure — they all land in the same catch block. You can't distinguish between them without inspecting the error string, which is fragile.

Errors lose their type across layers: By the time an UnauthorizedException from the API layer reaches the ViewModel, it's just an Object. All structural information is gone.

The solution is to make failures a first-class part of your function signatures, your type system, and your compiler checks. That is exactly what the patterns in this article do.

Part 1: Record Types as Lightweight Result Containers

What are Dart Records?

Dart 3.0 introduced Records — anonymous, immutable value types that group multiple fields together without needing a full class definition.

// A record with two named fields
({String name, int age}) person = (name: 'Seyi', age: 28);

print(person.name); // Seyi
print(person.age);  // 28

Records are structurally typed — two records with the same field names and types are the same type, regardless of where they were defined. They're also immutable and compare by value, not by reference.

Records as Result Types

The simplest application of records in error handling is encoding success and failure as a single return type with nullable fields:

typedef Result<E, T> = ({E? e, T? data});

This defines a record type with two nullable fields — e for the error and data for the success value. The contract is simple: exactly one of them will be non-null.

// On success — data is present, e is null
Result<String, User> result = (e: null, data: user);

// On failure — e is present, data is null
Result<String, User> result = (e: 'User not found', data: null);

This is already a significant improvement over exceptions. The return type now tells the caller that this function can produce either data or an error. The failure is part of the signature.

You can define more specific typedefs for different layers of your application:

typedef ApiResult<T, E>      = ({T? data, E? exception});
typedef SecurityResponse     = ({bool? isSecured, String? error});
typedef Repository<T>        = ApiResult<T, iException>;

Each typedef gives a meaningful name to a record shape, making the intent clear at every call site.

Sealed Classes as Namespaced Constructors

Creating result records manually every time is repetitive and error-prone. The cleanest solution is to use a sealed class purely as a namespace for static factory methods:

sealed class Res<E, T> {
  static Result<E, T> success<E, T>(T data) => (e: null, data: data);
  static Result<E, T> failure<E, T>(E e) => (e: e, data: null);
}

Notice what sealed is doing here: it's not being used for polymorphism. It can't be instantiated. It exists purely to group two related static methods under a meaningful, non-extendable name.

The call site becomes clean and intentional:

// In a repository
Future<Result<iException, User>> getUser(String id) async {
  try {
    final user = await _api.fetchUser(id);
    return Res.success(user);
  } on NetworkException catch (e) {
    return Res.failure(iException.internet(message: e.message));
  }
}

The same pattern applies for Dio-specific responses:

sealed class DioResult<T, E> {
  static ApiResult<T, E> success<T, E>(T data) => (data: data, exception: null);
  static ApiResult<T, E> failure<T, E>(E exception) => (data: null, exception: exception);
}

And for repository-level results with a simplified type alias:

// GET<E, T> is just ({E? e, T? res})
typedef New<T> = GET<iException, T>;

sealed class R<E, T> {
  static New<T> success<T>(T data) => (e: null, res: data);
  static New<T> failed<T>(iException error) => (e: error, res: null);
}

Each sealed class namespace has a single responsibility and maps to a single layer of the application.

Domain-Specific Record Types

Records also work beautifully for domain-specific result shapes that don't fit a generic success/failure pattern:

typedef SecurityResponse = ({bool? isSecured, String? error});

sealed class Check {
  static SecurityResponse isSecured() => (isSecured: true, error: null);
  static SecurityResponse isInsecured(String error) => (isSecured: false, error: error);
}

Using it:

final check = Check.isSecured();
if (check.isSecured == true) {
  // proceed
}

final check = Check.isInsecured('Certificate validation failed');
print(check.error); // Certificate validation failed

Clean, readable, and self-documenting. The record shape tells you exactly what the function can return.

The limitation to keep in mind: Record-based result types require you to manually check which field is non-null. There is no compiler enforcement that you handle both cases, and no built-in way to transform the result without unwrapping it manually. That's where a proper sealed Result type becomes necessary.

Part 2: Building a Proper Sealed Result Type

The AppResult Sealed Class

A sealed Result type goes further than a record — it uses Dart's type system to make the two possible states structurally distinct, and provides a when() method that forces the caller to handle both cases at compile time.

import 'app_failure.dart';

sealed class AppResult<T> {
  const AppResult();

  R when<R>({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  });
}

class AppSuccess<T> extends AppResult<T> {
  const AppSuccess(this.value);

  final T value;

  @override
  R when<R>({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  }) {
    return success(value);
  }
}

class AppFailureResult<T> extends AppResult<T> {
  const AppFailureResult(this.error);

  final AppFailure error;

  @override
  R when<R>({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  }) {
    return failure(error);
  }
}

Let's walk through the design decisions carefully.

sealed class AppResult<T>: sealed means all subtypes must live in the same file and the compiler knows every possible subtype. This is what enables exhaustive pattern matching. <T> is the type of data you get on success.

AppSuccess<T>: holds the actual data. When when() is called on an AppSuccess, it always calls the success callback and passes the value through.

AppFailureResult<T>: holds an AppFailure (your error model). When when() is called on an AppFailureResult, it always calls the failure callback. Notice it still carries <T> even though there is no value — this makes both subtypes compatible with the same AppResult<T> type.

The when() method: this is the key mechanism. Both callbacks are required. The compiler won't let you call when() without handling both cases. You can't forget the error path. You can't forget the success path. The object itself decides which branch runs — not an if/else in the calling code.

// Repository returning AppResult
Future<AppResult<User>> login(String email, String password) async {
  try {
    final user = await _api.login(email, password);
    return AppSuccess(user);
  } on UnauthorizedException {
    return AppFailureResult(AppFailure.unauthorized());
  } on NetworkException {
    return AppFailureResult(AppFailure.network());
  } catch (e) {
    return AppFailureResult(AppFailure.unknown(e.toString()));
  }
}

Consuming Results with when()

final result = await _repository.login(email, password);

result.when(
  success: (user) => emit(AuthState.authenticated(user)),
  failure: (error) => emit(AuthState.error(error.message)),
);

You can also use it to return values:

// Returning a Widget
final widget = result.when(
  success: (user) => UserProfileCard(user: user),
  failure: (error) => ErrorView(message: error.message),
);

// Returning a String
final message = result.when(
  success: (data) => 'Welcome back, ${data.name}',
  failure: (error) => 'Something went wrong: ${error.message}',
);

The return type R is inferred — whatever both callbacks return, when() returns. If they return a Widget, you get a Widget. If they return a String, you get a String.

Why This is Better

Part 3: Extending to the Monad Pattern

What Makes Something a Monad?

A monad is a pattern from functional programming. In practical terms, a type is monadic when it satisfies three things:

Wrap — you can put a value into the context.

AppSuccess(user) // wrapping a User into AppResult

Transform (map) — you can apply a function to the wrapped value without manually unwrapping it. If the result is a failure, the transformation is skipped and the failure propagates.

Chain (flatMap) — you can sequence multiple operations that each return the same wrapper type, without nesting. The first failure short-circuits the entire chain.

AppResult as defined above satisfies the first rule and the spirit of the second through when(). But without map and flatMap, it's not mechanically monadic. Let's fix that.

Adding map and flatMap

sealed class AppResult<T> {
  const AppResult();

  /// Transform the success value, propagate failure untouched
  AppResult<R> map<R>(R Function(T value) transform) {
    return when(
      success: (value) => AppSuccess(transform(value)),
      failure: (error) => AppFailureResult(error),
    );
  }

  /// Chain an operation that itself returns an AppResult
  AppResult<R> flatMap<R>(AppResult<R> Function(T value) transform) {
    return when(
      success: (value) => transform(value),
      failure: (error) => AppFailureResult(error),
    );
  }

  R when<R>({
    required R Function(T value) success,
    required R Function(AppFailure failure) failure,
  });
}

map transforms the success value using a regular function. If the result is already a failure, map skips the transformation entirely and passes the failure through unchanged. This is called "failure propagation" — errors flow through the chain automatically.

flatMap chains an operation that itself returns an AppResult. This is what allows sequencing — when each step in a process can independently succeed or fail, flatMap connects them so the first failure stops the chain.

Chaining Operations

Without monadic chaining, sequential operations that can each fail look like this:

final loginResult = await login(email, password);

loginResult.when(
  success: (user) async {
    final profileResult = await getProfile(user.id);
    profileResult.when(
      success: (profile) async {
        final settingsResult = await loadSettings(profile.settingsId);
        settingsResult.when(
          success: (settings) => emit(AppState.ready(settings)),
          failure: (error) => emit(AppState.error(error)),
        );
      },
      failure: (error) => emit(AppState.error(error)),
    );
  },
  failure: (error) => emit(AppState.error(error)),
);

Deeply nested, repetitive error handling on every single step. With flatMap:

final result = (await login(email, password))
    .flatMap((user) => getProfile(user.id))
    .flatMap((profile) => loadSettings(profile.settingsId))
    .map((settings) => settings.theme);

result.when(
  success: (theme) => emit(AppState.ready(theme)),
  failure: (error) => emit(AppState.error(error)),
);

Each step only runs if the previous one succeeded. The first failure short-circuits the entire chain. Error handling happens once at the end, not at every step. This is the full power of the monad pattern applied to real application code.

Part 4: Either with dartz

What is Either?

Either<L, R> is a type from functional programming that represents one of two possible values — a Left or a Right. By convention:

• Left — the failure case

• Right — the success case

The dartz package brings this and many other functional programming primitives to Dart. Add it to your project:

dependencies:
  dartz: ^0.10.1

In the codebase we are building from, Either is used with a type alias that makes the intent explicit:

import 'package:dartz/dartz.dart';

typedef API<T> = Either<T, iException>;

Note the convention here: Left holds the success value T, and Right holds the failure iException. This is intentionally flipped from the functional programming norm. Both conventions exist in real codebases — what matters is that you're consistent.

Using Either in Practice

Creating Either values:

// Success — Left holds the data
Either<User, iException> result = Left(user);

// Failure — Right holds the exception
Either<User, iException> result = Right(iException.internet(message: 'No connection'));

Checking which side you're on:

if (result.isLeft()) {
  final user = result.fold((user) => user, (_) => null);
}

Bridging Records and Either

The real power of the API typedef comes from ApiRes — a utility class that converts between the record-based world of your data layer and the Either-based world of your domain layer:

class ApiRes {
  static Future<API<T>> deserialize<T>(ApiResult<T, iException> res) async {
    return (res.data != null)
        ? Left(res.data as T)
        : Right(res.exception!);
  }

  static Future<API> deserializeDynamic(
    ApiResult<dynamic, iException> res,
  ) async {
    return (res.data != null) ? Left(res.data) : Right(res.exception!);
  }
}

ApiResult<T, iException> is your record type from the data layer — a Dio response wrapped with nullable fields. ApiRes.deserialize takes that record and converts it into a proper Either, ready to be used in the domain layer.

In practice, a repository method looks like this:

Future<API<User>> getUser(String id) async {
  // Data layer returns a record
  final res = await _dataSource.fetchUser(id);

  // Convert to Either at the boundary
  return ApiRes.deserialize<User>(res);
}

The boundary between layers is the conversion point. Inside the data layer, you work with records. At the boundary, you convert. In the domain layer, you work with Either. Each layer has the type that suits it best.

Folding an Either

dartz provides a fold method on Either that works similarly to when() on AppResult:

final result = await repository.getUser(id);

result.fold(
  (user) => emit(UserState.loaded(user)),       // Left — success
  (exception) => emit(UserState.error(exception.message)), // Right — failure
);

dartz also gives you monadic operations out of the box:

// map — transform the Left value
final nameResult = result.map((user) => user.name);

// flatMap / bind — chain Either-returning operations
final profileResult = result.flatMap(
  (user) => getProfile(user.id),
);

The full functional toolkit, ready to use without building it yourself.

Part 5: Typed Exceptions with Freezed

Why Freezed for Exceptions?

Standard Dart exceptions carry almost no useful information:

throw Exception('Something went wrong');
// At the catch site: what went wrong? what type? what code? who knows.

Even custom exception classes require significant boilerplate to implement properly — ==, hashCode, toString, immutability, copyWith. Freezed generates all of that automatically, and adds exhaustive pattern matching on top.

Add the required packages:

dependencies:
  freezed_annotation: ^2.4.1

dev_dependencies:
  freezed: ^2.4.5
  build_runner: ^2.4.6

Building iException

import 'package:flutter/foundation.dart';
import 'package:freezed_annotation/freezed_annotation.dart';

part 'exception.freezed.dart';

@freezed
class iException with _$iException {
  const factory iException.internet({
    required String message,
    int? code,
  }) = InternetException;

  const factory iException.mapper({
    required String message,
    int? code,
  }) = MapperException;

  const factory iException.validation({
    required String message,
    int? code,
  }) = ValidationException;

  const factory iException.unauthorized({
    required String message,
    int? code,
  }) = UnauthorizedException;

  const factory iException.unknown({
    required String message,
    int? code,
  }) = UnknownException;

  const iException._();
}

Run code generation:

flutter pub run build_runner build --delete-conflicting-outputs

What Freezed generates from this:

iException (sealed base)
├── InternetException    — network failures, no connectivity
├── MapperException      — JSON parsing and deserialization failures
├── ValidationException  — input validation failures
├── UnauthorizedException — auth failures, expired tokens
└── UnknownException     — catch-all for unexpected errors

Each subclass is fully immutable, has == and hashCode based on its fields, and a proper toString. Creating exceptions is clean and explicit:

iException.internet(message: 'No internet connection')
iException.unauthorized(message: 'Session expired', code: 401)
iException.validation(message: 'Email format is invalid')
iException.mapper(message: 'Failed to parse UserResponse', code: 500)
iException.unknown(message: e.toString())

The private constructor const iException._() is a Freezed requirement when you add any instance method or getter to the base class — it allows Freezed's generated subclasses to call super._() without exposing a public constructor on the base.

Pattern Matching on Exception Types

Because iException is a Freezed sealed class, you get when, maybeWhen, map, and maybeMap for free from code generation:

exception.when(
  internet: (message, code) => 'No internet: $message',
  mapper: (message, code) => 'Parse error: $message',
  validation: (message, code) => 'Invalid input: $message',
  unauthorized: (message, code) => 'Unauthorised — please log in again',
  unknown: (message, code) => 'Unexpected error: $message',
);

Every case is required. The compiler rejects incomplete matches. You can't accidentally handle only some exception types and silently miss others.

For cases where you only care about specific types:

exception.maybeWhen(
  unauthorized: (message, code) => _redirectToLogin(),
  orElse: () => _showGenericError(exception),
);

A Cleaner Base Getter Pattern

One thing worth improving in the base iException is providing a safe message getter that works across all subtypes without throwing UnimplementedError:

const iException._();

String get displayMessage => when(
  internet: (message, _) => message,
  mapper: (message, _) => message,
  validation: (message, _) => message,
  unauthorized: (message, _) => message,
  unknown: (message, _) => message,
);

Now any code holding an iException — regardless of which subtype — can call .displayMessage safely:

// In a ViewModel or BLoC — no need to pattern match just for the message
emit(ErrorState(message: exception.displayMessage));

This is significantly cleaner than a base getter that throws UnimplementedError at runtime.

Part 6: Putting It All Together

The Full Architecture

Here's how all four patterns connect across a real clean architecture Flutter application:

Data Layer
  Dio/HTTP call returns raw response
    └── Wrapped in ApiResult<T, iException> (record type)
          │
          ▼
Repository Layer
  ApiRes.deserialize() converts record → Either<T, iException>
    └── Returns API<T> = Either<T, iException>
          │
          ▼
Domain / Use Case Layer
  AppResult<T> is the standard return type
    └── Sealed class with AppSuccess and AppFailureResult
          │
          ▼
Presentation Layer
  result.when() handles both paths
    └── exception.when() handles all failure types

Each layer has the result type that suits its responsibility. Conversion happens at the boundaries. The presentation layer always deals with AppResult<T> — it doesn't need to know about Either or records.

Repository Layer

class AuthRepository {
  final AuthDataSource _dataSource;

  AuthRepository(this._dataSource);

  Future<AppResult<User>> login(String email, String password) async {
    // Data source returns a record
    final res = await _dataSource.login(email, password);

    // Convert to Either at the data/domain boundary
    final either = await ApiRes.deserialize<User>(res);

    // Convert Either to AppResult for the domain layer
    return either.fold(
      (user) => AppSuccess(user),
      (exception) => AppFailureResult(exception),
    );
  }

  Future<AppResult<List<User>>> getUsers() async {
    final res = await _dataSource.fetchUsers();
    final either = await ApiRes.deserialize<List<User>>(res);

    return either.fold(
      (users) => AppSuccess(users),
      (exception) => AppFailureResult(exception),
    );
  }
}

Domain Layer

class LoginUseCase {
  final AuthRepository _repository;

  LoginUseCase(this._repository);

  Future<AppResult<User>> execute(String email, String password) async {
    if (email.isEmpty || password.isEmpty) {
      return AppFailureResult(
        iException.validation(message: 'Email and password are required'),
      );
    }

    return _repository.login(email, password);
  }
}

The use case adds its own validation layer — returning a ValidationException before even hitting the repository. All failures flow through the same AppResult<T> type regardless of where they originated.

Presentation Layer

class AuthViewModel extends ChangeNotifier {
  final LoginUseCase _loginUseCase;

  AuthViewModel(this._loginUseCase);

  AuthState _state = const AuthState.idle();
  AuthState get state => _state;

  Future<void> login(String email, String password) async {
    _state = const AuthState.loading();
    notifyListeners();

    final result = await _loginUseCase.execute(email, password);

    result.when(
      success: (user) {
        _state = AuthState.authenticated(user);
      },
      failure: (exception) {
        // Pattern match on the exception type for specific handling
        final message = exception.when(
          internet: (msg, _) => 'No internet connection. Please check your network.',
          unauthorized: (msg, _) => 'Your session has expired. Please log in again.',
          validation: (msg, _) => msg,
          mapper: (msg, _) => 'Something went wrong. Please try again.',
          unknown: (msg, _) => 'An unexpected error occurred.',
        );

        _state = AuthState.error(message);
      },
    );

    notifyListeners();
  }
}

Two levels of exhaustive pattern matching — one for the result, one for the exception type. Every possible failure has a specific, user-friendly message. The compiler guarantees nothing is missed.

And using the monadic chain from Part 3 for a multi-step flow:

Future<void> loadDashboard(String userId) async {
  _state = const DashboardState.loading();
  notifyListeners();

  final result = (await _userRepo.getUser(userId))
      .flatMap((user) => _profileRepo.getProfile(user.profileId))
      .flatMap((profile) => _settingsRepo.loadSettings(profile.settingsId))
      .map((settings) => DashboardData(settings: settings));

  result.when(
    success: (data) => _state = DashboardState.loaded(data),
    failure: (exception) => _state = DashboardState.error(
      exception.displayMessage,
    ),
  );

  notifyListeners();
}

Three sequential async operations, each of which can independently fail, handled in a clean chain with a single error handler at the end. This is what production-grade error handling looks like.

Conclusion

Error handling is one of those things that every codebase has, but few codebases have done well. The default in Dart , throwing and catching exceptions, is convenient for small projects and becomes a liability at scale. Failures become invisible, type information is lost across layers, and the compiler can't help you when something goes wrong.

The patterns in this article change that entirely.

Records give you lightweight result containers with zero boilerplate — perfect for layer-specific result types and domain-specific responses. Sealed Result types bring compiler enforcement — both paths are required, no failure can be silently ignored. The Monad pattern adds the ability to chain sequential operations cleanly, with automatic failure propagation through the chain. Either with dartz brings the full functional toolkit and a clean boundary type between your data and domain layers. And Freezed exceptions give your failure states structure, immutability, and exhaustive pattern matching, so every error type is handled explicitly and nothing slips through.

None of these patterns are complicated once you understand the problem they solve. And the problem they solve – invisible, unenforceable, type-unsafe error handling – is one of the most common sources of production bugs in Flutter applications.

The next step is taking one of these patterns into a real project. Using these will totally transform the error handling story and processes of your entire code base.

Yet most developers have never built one.

That's a missed opportunity. CLI tools are one of the most practical things a developer can ship. They automate repetitive workflows, standardise processes across teams, and, when published, become tangible artifacts that the developer community can discover, install, and use.

In this handbook, you'll go from zero to building a fully distributed Dart CLI tool. We'll start with the fundamentals – how CLIs work, how Dart receives and processes terminal input, and the core syntax you need to know. Then we'll build three progressively complex CLIs, starting with the basics and finishing with a real-world API request runner. Finally, we will cover every distribution path available, from pub.dev to compiled binaries, Homebrew taps, Docker, and local team activation.

By the end of the guide, you'll understand both how to build a CLI tool in Dart as well as how to ship it so other developers can actually use it.

Table of Contents

• Prerequisites

• What is a CLI and Why Should You Build One?

• CLI Syntax Anatomy

• How Dart Receives Terminal Input

• Core CLI Concepts in Dart

  • stdout, stderr, and stdin

  • Exit Codes

  • Environment Variables

  • File and Directory Operations

  • Running External Processes

  • Platform Detection

  • Async in CLI

• Setting Up Your Dart CLI Project

• CLI 1 — Hello CLI: The Fundamentals

• CLI 2 — dart_todo: A Terminal Task Manager

  • Introducing the args Package

  • Building dart_todo

• CLI 3 — dart_http: A Lightweight API Request Runner

  • Building dart_http

• Adding Color and Polish to Your CLI

• Testing Your CLI Tool

• Deploying and Distributing Your CLI

  • Mode 1: pub.dev — Public Package Distribution

  • Mode 2: Local Path Activation

  • Mode 3: Compiled Binary via GitHub Releases

  • Mode 4: Homebrew Tap

  • Mode 5: Docker

• Choosing the Right Distribution Mode

• Conclusion

Prerequisites

Before starting, you should have:

• Dart SDK installed (dart --version should work in your terminal)

• Basic familiarity with Dart syntax

• Comfort with the terminal and running commands

• A pub.dev account (for the publishing section)

• A GitHub account (for the binary distribution section)

What is a CLI and Why Should You Build One?

A CLI (or Command Line Interface) is a program you interact with entirely through text commands in a terminal, rather than through buttons and screens in a graphical interface.

Many of the tools you likely already rely on as a developer are CLI tools:

flutter build apk
git commit -m "fix: auth flow"
dart pub get
npm install

Flutter, Git, Dart, npm – all CLIs. You are already a CLI user every single day. This article is about becoming a CLI builder.

There are three strong reasons to build CLI tools as a developer:

1. Automating repetitive work: Anything you type more than twice a week is a candidate for automation. Generating boilerplate folder structures, running sequences of commands, scaffolding files, checking environments before a build a CLI turns a seven-step manual process into a single command.

2. Standardising team workflows: Instead of a README that says "run these commands in this order," you ship one command that does all of it – consistently, every time, with no room for human error or a missed step.

3. Building and publishing tooling. A published Dart CLI package is a tangible artifact. It shows up on pub.dev, gets installed and used by other developers, and communicates real engineering depth in a way that a portfolio or resume cannot.

CLI Syntax Anatomy

Before writing a single line of code, it helps to understand the structure of a CLI command. Every command follows a consistent pattern:

tool [subcommand] [arguments] [options/flags]

Breaking down a real example:

flutter build apk --release --obfuscate
│       │     │   │
tool    sub   arg  flags

• Tool — the program itself (flutter, dart, git)

• Subcommand — the action being performed (build, run, pub)

• Arguments — what the action operates on (apk, main.dart, a filename)

• Flags and Options — modifiers that change behaviour

There are two types of options:

--release              # Boolean flag — either present or absent

--output=build/app     # Key-value option — name and a value
-v                     # Short flag — single hyphen, single character

This is the anatomy your CLIs will follow. Understanding it before writing any code means you will design your commands intentionally rather than stumbling into structure by accident.

How Dart Receives Terminal Input

In Dart, everything the user types after your tool name is passed into your program through the main function:

void main(List<String> args) {
  print(args);
}

Run it:

dart run bin/mytool.dart hello world --name=Seyi
# [hello, world, --name=Seyi]

That List<String> args is just a list of strings. Each word or flag the user typed becomes an element in that list. Everything else you build on top of a CLI subcommands, flags, validation — is ultimately just processing this list.

Core CLI Concepts in Dart

Before building anything, there's a set of foundational concepts that every CLI developer needs to understand. These are the building blocks that everything else sits on top of.

stdout, stderr, and stdin

Most developers use print() for all output when they start building CLIs. That works for learning but it's incorrect in production.

There are two separate output streams in a terminal program:

• stdout — regular output, meant for the user

• stderr — error output, meant for diagnostic messages and failures

import 'dart:io';

void main(List<String> args) {
  if (args.isEmpty) {
    stderr.writeln('Error: no arguments provided');
    exit(1);
  }

  stdout.writeln('Processing: ${args[0]}');
}

Keeping these separate matters because users can redirect stdout to a file without errors polluting it:

dart run bin/tool.dart > output.txt
# Errors still appear in the terminal
# Normal output goes cleanly to the file

Tools like git, flutter, and curl all do this correctly. Your CLI should too.

stdin is the third stream — reading input from the user interactively at runtime:

import 'dart:io';

void main() {
  stdout.write('Enter your name: ');
  final name = stdin.readLineSync();

  if (name == null || name.trim().isEmpty) {
    stderr.writeln('Error: no name provided');
    exit(1);
  }

  stdout.writeln('Hello, $name!');
}

stdout.write (without ln) keeps the cursor on the same line so the user types right after the prompt. stdin.readLineSync() blocks until the user presses Enter and returns the typed string, or null if the stream closes unexpectedly. Always handle the null case.

Exit Codes

Every program returns an exit code when it finishes. This is how the shell – and any script or CI system calling your tool – knows whether it succeeded or failed.

import 'dart:io';

void main(List<String> args) {
  if (args.isEmpty) {
    stderr.writeln('Error: please provide an argument');
    exit(1); // failure
  }

  stdout.writeln('Done');
  exit(0); // success — also the default if you don't call exit()
}

The conventions are:

• 0 — success

• 1 — general failure

• 2 — incorrect usage (wrong arguments, missing flags)

Exit codes are critical when your CLI is called inside shell scripts or GitHub Actions workflows. A non-zero exit code stops a pipeline immediately. That's exactly the behaviour you want from a quality gate or a validation step.

Environment Variables

Your CLI can read environment variables set in the user's shell:

import 'dart:io';

void main() {
  final token = Platform.environment['API_TOKEN'];

  if (token == null) {
    stderr.writeln('Error: API_TOKEN environment variable is not set');
    exit(1);
  }

  stdout.writeln('Token found — proceeding...');
}

Set it in the terminal and run:

export API_TOKEN=mytoken123
dart run bin/tool.dart
# Token found — proceeding...

This pattern is essential for CLI tools that interact with APIs, cloud services, or CI environments where credentials should never be hardcoded.

File and Directory Operations

Many CLI tools read from or write to the file system. Dart's dart:io library covers everything you need:

import 'dart:io';

void main(List<String> args) {
  if (args.isEmpty) {
    stderr.writeln('Usage: tool <filename>');
    exit(2);
  }

  final file = File(args[0]);

  if (!file.existsSync()) {
    stderr.writeln('Error: "${args[0]}" not found');
    exit(1);
  }

  final contents = file.readAsStringSync();
  stdout.writeln(contents);

  final output = File('output.txt');
  output.writeAsStringSync('Processed:\n$contents');
  stdout.writeln('Written to output.txt');
}

Working with directories:

import 'dart:io';

void main() {
  // Where the command was run from
  final cwd = Directory.current.path;
  stdout.writeln('Working directory: $cwd');

  // Create a directory relative to current location
  final dir = Directory('$cwd/generated');

  if (!dir.existsSync()) {
    dir.createSync(recursive: true);
    stdout.writeln('Created: ${dir.path}');
  } else {
    stdout.writeln('Already exists: ${dir.path}');
  }
}

The recursive: true flag on createSync means it creates all intermediate directories — equivalent to mkdir -p in bash.

Running External Processes

One of the most powerful things a CLI can do is call other programs. Your Dart CLI can run git, flutter, dart, or any shell command programmatically:

import 'dart:io';

void main() async {
  // Run a command and wait for it to finish
  final result = await Process.run('dart', ['pub', 'get']);

  stdout.write(result.stdout);

  if (result.exitCode != 0) {
    stderr.write(result.stderr);
    exit(result.exitCode);
  }

  stdout.writeln('Dependencies installed successfully');
}

For long-running commands where you want output to stream live as it happens:

import 'dart:io';

void main() async {
  final process = await Process.start('flutter', ['build', 'apk']);

  // Pipe output directly to the terminal in real time
  process.stdout.pipe(stdout);
  process.stderr.pipe(stderr);

  final exitCode = await process.exitCode;
  exit(exitCode);
}

Process.run — waits for completion, returns all output at once. Use for short commands.

Process.start — streams output live as it arrives. Use for long-running commands where the user needs to see progress.

Platform Detection

Sometimes your CLI needs to behave differently depending on the operating system it is running on:

import 'dart:io';

void main() {
  if (Platform.isWindows) {
    stdout.writeln('Running on Windows');
  } else if (Platform.isMacOS) {
    stdout.writeln('Running on macOS');
  } else if (Platform.isLinux) {
    stdout.writeln('Running on Linux');
  }

  // Useful for path handling across operating systems
  stdout.writeln(Platform.pathSeparator); // \ on Windows, / elsewhere
  stdout.writeln(Platform.operatingSystem); // 'macos', 'linux', 'windows'
}

This matters when your CLI creates files, resolves paths, or calls shell commands that differ between operating systems.

Async in CLI

Dart CLIs support async/await natively. Any main function can be made async:

import 'dart:io';

void main() async {
  stdout.writeln('Starting...');

  await Future.delayed(const Duration(seconds: 1)); // simulating async work

  stdout.writeln('Done');
}

Any operation involving file I/O, HTTP requests, or spawning processes will be asynchronous. Get comfortable with async main functions early — you'll use them constantly.

Setting Up Your Dart CLI Project

Create a new Dart console project:

dart create -t console my_cli_tool
cd my_cli_tool

This generates a clean structure:

my_cli_tool/
  bin/
    my_cli_tool.dart    ← entry point
  lib/                  ← shared library code
  test/                 ← tests
  pubspec.yaml
  README.md

The bin/ directory is where your executable entry point lives. The lib/ directory is where you put everything else — commands, utilities, models — that bin/ imports and uses.

Open pubspec.yaml. You'll need to add an executables block before publishing:

name: my_cli_tool
description: A sample CLI tool built with Dart
version: 1.0.0

environment:
  sdk: '>=3.0.0 <4.0.0'

executables:
  my_cli_tool: my_cli_tool  # executable name: bin file name

dependencies:
  args: ^2.4.2

dev_dependencies:
  lints: ^3.0.0
  test: ^1.24.0

The executables block is what makes dart pub global activate my_cli_tool work. It tells Dart which script in bin/ to expose as a runnable command after installation.

CLI 1 — Hello CLI: The Fundamentals

This first CLI uses pure Dart — no packages. The goal is to get comfortable with args, subcommands, input validation, and exit codes before introducing any external dependencies.

Replace the contents of bin/my_cli_tool.dart:

import 'dart:io';

void main(List<String> args) {
  if (args.isEmpty) {
    printHelp();
    exit(0);
  }

  final command = args[0];

  switch (command) {
    case 'greet':
      handleGreet(args.sublist(1));
    case 'time':
      handleTime();
    case 'echo':
      handleEcho(args.sublist(1));
    case 'help':
      printHelp();
    default:
      stderr.writeln('Unknown command: "$command"');
      stderr.writeln('Run "mytool help" to see available commands.');
      exit(1);
  }
}

void handleGreet(List<String> args) {
  if (args.isEmpty) {
    stderr.writeln('Usage: mytool greet <name>');
    exit(2);
  }

  final name = args[0];
  stdout.writeln('Hello, $name! Welcome to your first Dart CLI.');
}

void handleTime() {
  final now = DateTime.now();
  stdout.writeln(
    'Current time: ${now.hour.toString().padLeft(2, '0')}:'
    '${now.minute.toString().padLeft(2, '0')}:'
    '${now.second.toString().padLeft(2, '0')}',
  );
}

void handleEcho(List<String> args) {
  if (args.isEmpty) {
    stderr.writeln('Usage: mytool echo <message>');
    exit(2);
  }

  stdout.writeln(args.join(' '));
}

void printHelp() {
  stdout.writeln('''
mytool — a simple Dart CLI

Usage:
  mytool <command> [arguments]

Commands:
  greet <name>      Greet someone by name
  time              Show the current time
  echo <message>    Echo a message back to the terminal
  help              Show this help message

Examples:
  mytool greet Seyi
  mytool echo "Hello from the terminal"
  mytool time
  ''');
}

Run it:

dart run bin/my_cli_tool.dart help

dart run bin/my_cli_tool.dart greet Seyi
# Hello, Seyi! Welcome to your first Dart CLI.

dart run bin/my_cli_tool.dart time
# Current time: 14:32:10

dart run bin/my_cli_tool.dart echo "Dart CLIs are powerful"
# Dart CLIs are powerful

dart run bin/my_cli_tool.dart unknown
# Unknown command: "unknown"
# Run "mytool help" to see available commands.

Three things this CLI demonstrates that are worth internalising:

1. Subcommands are just a switch on args[0]. The pattern is simple and scalable — add a new case to add a new command.

2. args.sublist(1) passes remaining args to the handler. When greet receives ['greet', 'Seyi'], it calls handleGreet(['Seyi']) — clean and isolated.

3. Every error path has a message and a non-zero exit code. The user always knows what went wrong and what to do next.

CLI 2 — dart_todo: A Terminal Task Manager

This CLI introduces the args package, JSON file persistence, and structured terminal output. It's meaningfully more complex than CLI 1 and reflects real patterns you will use in production tools.

Introducing the args Package

Manually parsing List<String> args works for simple cases, but breaks down quickly when you add flags like --priority=high, boolean options like --done, or commands with multiple optional arguments.

The args package handles all of that cleanly.

Add it to your pubspec.yaml:

dependencies:
  args: ^2.4.2

Run:

dart pub get

The core concept in args is the ArgParser. You define what your CLI accepts, and args handles parsing, validation, and generating help text automatically:

import 'package:args/args.dart';

void main(List<String> arguments) {
  final parser = ArgParser()
    ..addCommand('add')
    ..addCommand('list')
    ..addFlag('help', abbr: 'h', negatable: false);

  final results = parser.parse(arguments);

  if (results['help'] as bool) {
    print(parser.usage);
    return;
  }
}

For more complex CLIs with subcommands that each have their own flags, use ArgParser per command:

final parser = ArgParser();

final addCommand = ArgParser()
  ..addOption('priority', abbr: 'p', defaultsTo: 'normal');

parser.addCommand('add', addCommand);

Building dart_todo

Create a fresh project:

dart create -t console dart_todo
cd dart_todo

Update pubspec.yaml:

name: dart_todo
description: A terminal task manager built with Dart
version: 1.0.0

environment:
  sdk: '>=3.0.0 <4.0.0'

executables:
  dart_todo: dart_todo

dependencies:
  args: ^2.4.2

dev_dependencies:
  lints: ^3.0.0
  test: ^1.24.0

Run dart pub get.

Create the folder structure:

dart_todo/
  bin/
    dart_todo.dart
  lib/
    models/
      task.dart
    storage/
      task_storage.dart
    commands/
      add_command.dart
      list_command.dart
      complete_command.dart
      delete_command.dart
      clear_command.dart
  pubspec.yaml

Step 1 — The Task Model (lib/models/task.dart)

class Task {
  final int id;
  final String title;
  final String priority;
  final bool isComplete;
  final DateTime createdAt;

  Task({
    required this.id,
    required this.title,
    required this.priority,
    this.isComplete = false,
    required this.createdAt,
  });

  Task copyWith({bool? isComplete}) {
    return Task(
      id: id,
      title: title,
      priority: priority,
      isComplete: isComplete ?? this.isComplete,
      createdAt: createdAt,
    );
  }

  Map<String, dynamic> toJson() => {
        'id': id,
        'title': title,
        'priority': priority,
        'isComplete': isComplete,
        'createdAt': createdAt.toIso8601String(),
      };

  factory Task.fromJson(Map<String, dynamic> json) => Task(
        id: json['id'] as int,
        title: json['title'] as String,
        priority: json['priority'] as String,
        isComplete: json['isComplete'] as bool,
        createdAt: DateTime.parse(json['createdAt'] as String),
      );
}

Step 2 — Storage (lib/storage/task_storage.dart)

This class handles reading and writing tasks to a local JSON file so they persist between CLI runs:

import 'dart:convert';
import 'dart:io';

import '../models/task.dart';

class TaskStorage {
  static final _file = File(
    '${Platform.environment['HOME'] ?? Directory.current.path}/.dart_todo.json',
  );

  static List<Task> loadAll() {
    if (!_file.existsSync()) return [];

    try {
      final content = _file.readAsStringSync();
      final List<dynamic> json = jsonDecode(content) as List<dynamic>;
      return json
          .map((e) => Task.fromJson(e as Map<String, dynamic>))
          .toList();
    } catch (_) {
      return [];
    }
  }

  static void saveAll(List<Task> tasks) {
    final json = jsonEncode(tasks.map((t) => t.toJson()).toList());
    _file.writeAsStringSync(json);
  }
}

Tasks are stored in a hidden JSON file in the user's home directory — a common pattern for CLI tools that need lightweight local persistence.

Step 3 — Commands

lib/commands/add_command.dart:

import 'dart:io';

import '../models/task.dart';
import '../storage/task_storage.dart';

void runAdd(List<String> args, String priority) {
  if (args.isEmpty) {
    stderr.writeln('Usage: dart_todo add <title> [--priority=high|normal|low]');
    exit(2);
  }

  final title = args.join(' ');
  final tasks = TaskStorage.loadAll();

  final newTask = Task(
    id: tasks.isEmpty ? 1 : tasks.last.id + 1,
    title: title,
    priority: priority,
    createdAt: DateTime.now(),
  );

  tasks.add(newTask);
  TaskStorage.saveAll(tasks);

  stdout.writeln('Added task #\({newTask.id}: "\)title" [$priority]');
}

lib/commands/list_command.dart:

import 'dart:io';

import '../storage/task_storage.dart';

void runList() {
  final tasks = TaskStorage.loadAll();

  if (tasks.isEmpty) {
    stdout.writeln('No tasks yet. Add one with: dart_todo add <title>');
    return;
  }

  stdout.writeln('');
  stdout.writeln('  ID   Status      Priority   Title');
  stdout.writeln('  ───  ──────────  ─────────  ────────────────────────');

  for (final task in tasks) {
    final status = task.isComplete ? 'done  ' : 'pending';
    final id = task.id.toString().padRight(4);
    final priority = task.priority.padRight(9);
    stdout.writeln('  \(id \)status  \(priority  \){task.title}');
  }

  stdout.writeln('');
}

lib/commands/complete_command.dart:

import 'dart:io';

import '../storage/task_storage.dart';

void runComplete(List<String> args) {
  if (args.isEmpty) {
    stderr.writeln('Usage: dart_todo complete <id>');
    exit(2);
  }

  final id = int.tryParse(args[0]);
  if (id == null) {
    stderr.writeln('Error: "${args[0]}" is not a valid task ID');
    exit(1);
  }

  final tasks = TaskStorage.loadAll();
  final index = tasks.indexWhere((t) => t.id == id);

  if (index == -1) {
    stderr.writeln('Error: No task found with ID $id');
    exit(1);
  }

  if (tasks[index].isComplete) {
    stdout.writeln('Task #$id is already complete.');
    return;
  }

  tasks[index] = tasks[index].copyWith(isComplete: true);
  TaskStorage.saveAll(tasks);

  stdout.writeln('Task #\(id marked as complete: "\){tasks[index].title}"');
}

lib/commands/delete_command.dart:

import 'dart:io';

import '../storage/task_storage.dart';

void runDelete(List<String> args) {
  if (args.isEmpty) {
    stderr.writeln('Usage: dart_todo delete <id>');
    exit(2);
  }

  final id = int.tryParse(args[0]);
  if (id == null) {
    stderr.writeln('Error: "${args[0]}" is not a valid task ID');
    exit(1);
  }

  final tasks = TaskStorage.loadAll();
  final index = tasks.indexWhere((t) => t.id == id);

  if (index == -1) {
    stderr.writeln('Error: No task found with ID $id');
    exit(1);
  }

  final title = tasks[index].title;
  tasks.removeAt(index);
  TaskStorage.saveAll(tasks);

  stdout.writeln('Deleted task #\(id: "\)title"');
}

lib/commands/clear_command.dart:

import 'dart:io';

import '../storage/task_storage.dart';

void runClear() {
  stdout.write('Are you sure you want to delete all tasks? (y/N): ');
  final input = stdin.readLineSync()?.trim().toLowerCase();

  if (input != 'y') {
    stdout.writeln('Cancelled.');
    return;
  }

  TaskStorage.saveAll([]);
  stdout.writeln('All tasks cleared.');
}

Step 4 — Entry Point (bin/dart_todo.dart)

import 'dart:io';

import 'package:args/args.dart';

import '../lib/commands/add_command.dart';
import '../lib/commands/clear_command.dart';
import '../lib/commands/complete_command.dart';
import '../lib/commands/delete_command.dart';
import '../lib/commands/list_command.dart';

void main(List<String> arguments) {
  final parser = ArgParser();

  // Add subcommand parsers
  final addParser = ArgParser()
    ..addOption(
      'priority',
      abbr: 'p',
      defaultsTo: 'normal',
      allowed: ['high', 'normal', 'low'],
      help: 'Task priority level',
    );

  parser
    ..addCommand('add', addParser)
    ..addCommand('list')
    ..addCommand('complete')
    ..addCommand('delete')
    ..addCommand('clear')
    ..addFlag('help', abbr: 'h', negatable: false, help: 'Show help');

  ArgResults results;

  try {
    results = parser.parse(arguments);
  } catch (e) {
    stderr.writeln('Error: $e');
    stderr.writeln(parser.usage);
    exit(2);
  }

  if (results['help'] as bool || results.command == null) {
    printHelp(parser);
    exit(0);
  }

  final command = results.command!;

  switch (command.name) {
    case 'add':
      runAdd(command.rest, command['priority'] as String);
    case 'list':
      runList();
    case 'complete':
      runComplete(command.rest);
    case 'delete':
      runDelete(command.rest);
    case 'clear':
      runClear();
    default:
      stderr.writeln('Unknown command: "${command.name}"');
      exit(1);
  }
}

void printHelp(ArgParser parser) {
  stdout.writeln('''
dart_todo — a terminal task manager

Usage:
  dart_todo <command> [arguments]

Commands:
  add <title>        Add a new task
    -p, --priority   Priority: high, normal, low (default: normal)
  list               List all tasks
  complete <id>      Mark a task as complete
  delete <id>        Delete a task
  clear              Delete all tasks

Examples:
  dart_todo add "Write the CLI article" --priority=high
  dart_todo list
  dart_todo complete 1
  dart_todo delete 2
  dart_todo clear
  ''');
}

Run it:

dart run bin/dart_todo.dart add "Write the CLI article" --priority=high
# Added task #1: "Write the CLI article" [high]

dart run bin/dart_todo.dart add "Review PR comments"
# Added task #2: "Review PR comments" [normal]

dart run bin/dart_todo.dart list
#   ID   Status      Priority   Title
#   ───  ──────────  ─────────  ────────────────────────
#   1    ⬜ pending  high       Write the CLI article
#   2    ⬜ pending  normal     Review PR comments

dart run bin/dart_todo.dart complete 1
# Task #1 marked as complete: "Write the CLI article"

dart run bin/dart_todo.dart delete 2
# Deleted task #2: "Review PR comments"

dart_todo demonstrates the patterns that form the backbone of almost every real CLI tool — argument parsing with args, JSON persistence, interactive prompts, structured output, and clean error handling across every command.

CLI 3 — dart_http: A Lightweight API Request Runner

This is the most complex CLI in this article – and the most immediately useful. dart_http lets developers make HTTP requests directly from the terminal, with pretty-printed JSON responses, response metadata, header support, and the ability to save responses to a file.

dart_http get https://jsonplaceholder.typicode.com/users/1
dart_http post https://jsonplaceholder.typicode.com/posts --body='{"title":"Hello"}'
dart_http get https://jsonplaceholder.typicode.com/users --save=users.json
dart_http get https://api.example.com/me --header="Authorization: Bearer mytoken"

Building dart_http

Create the project:

dart create -t console dart_http
cd dart_http

Update pubspec.yaml:

name: dart_http
description: A lightweight API request runner for the terminal
version: 1.0.0

environment:
  sdk: '>=3.0.0 <4.0.0'

executables:
  dart_http: dart_http

dependencies:
  args: ^2.4.2
  http: ^1.2.1

dev_dependencies:
  lints: ^3.0.0
  test: ^1.24.0

Run dart pub get.

Project structure:

dart_http/
  bin/
    dart_http.dart
  lib/
    runner/
      request_runner.dart
    printer/
      response_printer.dart
    utils/
      headers_parser.dart
  pubspec.yaml

Step 1 — Headers Parser (lib/utils/headers_parser.dart)

Map<String, String> parseHeaders(List<String> rawHeaders) {
  final headers = <String, String>{};

  for (final header in rawHeaders) {
    final index = header.indexOf(':');
    if (index == -1) continue;

    final key = header.substring(0, index).trim();
    final value = header.substring(index + 1).trim();
    headers[key] = value;
  }

  return headers;
}

Step 2 — Response Printer (lib/printer/response_printer.dart)

import 'dart:convert';
import 'dart:io';

void printResponse({
  required int statusCode,
  required String body,
  required int durationMs,
  required int bodyBytes,
}) {
  final statusLabel = _statusLabel(statusCode);
  final size = _formatSize(bodyBytes);

  stdout.writeln('');
  stdout.writeln('\(statusLabel | \){durationMs}ms | $size');
  stdout.writeln('─' * 50);

  try {
    final decoded = jsonDecode(body);
    const encoder = JsonEncoder.withIndent('  ');
    stdout.writeln(encoder.convert(decoded));
  } catch (_) {
    // Not JSON — print as plain text
    stdout.writeln(body);
  }

  stdout.writeln('');
}

String _statusLabel(int code) {
  if (code >= 200 && code < 300) return '✅ $code';
  if (code >= 300 && code < 400) return '↪️  $code';
  if (code >= 400 && code < 500) return '❌ $code';
  return '$code';
}

String _formatSize(int bytes) {
  if (bytes < 1024) return '${bytes}b';
  if (bytes < 1024 * 1024) return '${(bytes / 1024).toStringAsFixed(1)}kb';
  return '${(bytes / (1024 * 1024)).toStringAsFixed(1)}mb';
}

Step 3 — Request Runner (lib/runner/request_runner.dart)

import 'dart:io';

import 'package:http/http.dart' as http;

import '../printer/response_printer.dart';

Future<void> runRequest({
  required String method,
  required String url,
  required Map<String, String> headers,
  String? body,
  String? saveToFile,
}) async {
  final uri = Uri.tryParse(url);

  if (uri == null) {
    stderr.writeln('Error: "$url" is not a valid URL');
    exit(1);
  }

  stdout.writeln('→ \({method.toUpperCase()} \)url');

  http.Response response;
  final stopwatch = Stopwatch()..start();

  try {
    switch (method.toLowerCase()) {
      case 'get':
        response = await http.get(uri, headers: headers);
      case 'post':
        response = await http.post(uri, headers: headers, body: body);
      case 'put':
        response = await http.put(uri, headers: headers, body: body);
      case 'patch':
        response = await http.patch(uri, headers: headers, body: body);
      case 'delete':
        response = await http.delete(uri, headers: headers);
      default:
        stderr.writeln('Error: unsupported method "$method"');
        exit(2);
    }
  } catch (e) {
    stderr.writeln('Error: request failed — $e');
    exit(1);
  }

  stopwatch.stop();

  printResponse(
    statusCode: response.statusCode,
    body: response.body,
    durationMs: stopwatch.elapsedMilliseconds,
    bodyBytes: response.bodyBytes.length,
  );

  if (saveToFile != null) {
    final file = File(saveToFile);
    file.writeAsStringSync(response.body);
    stdout.writeln('Response saved to $saveToFile');
  }
}

Step 4 — Entry Point (bin/dart_http.dart)

import 'dart:io';

import 'package:args/args.dart';

import '../lib/runner/request_runner.dart';
import '../lib/utils/headers_parser.dart';

void main(List<String> arguments) async {
  final parser = ArgParser();

  for (final method in ['get', 'post', 'put', 'patch', 'delete']) {
    final commandParser = ArgParser()
      ..addMultiOption('header', abbr: 'H', help: 'Request header (repeatable)')
      ..addOption('body', abbr: 'b', help: 'Request body (for POST/PUT/PATCH)')
      ..addOption('save', abbr: 's', help: 'Save response body to a file');

    parser.addCommand(method, commandParser);
  }

  parser.addFlag('help', abbr: 'h', negatable: false, help: 'Show help');

  ArgResults results;

  try {
    results = parser.parse(arguments);
  } catch (e) {
    stderr.writeln('Error: $e');
    printHelp();
    exit(2);
  }

  if (results['help'] as bool || results.command == null) {
    printHelp();
    exit(0);
  }

  final command = results.command!;
  final method = command.name!;
  final rest = command.rest;

  if (rest.isEmpty) {
    stderr.writeln('Error: please provide a URL');
    stderr.writeln('Usage: dart_http $method <url>');
    exit(2);
  }

  final url = rest[0];
  final rawHeaders = command['header'] as List<String>;
  final body = command['body'] as String?;
  final saveToFile = command['save'] as String?;

  final headers = parseHeaders(rawHeaders);

  // Default Content-Type for requests with a body
  if (body != null && !headers.containsKey('Content-Type')) {
    headers['Content-Type'] = 'application/json';
  }

  await runRequest(
    method: method,
    url: url,
    headers: headers,
    body: body,
    saveToFile: saveToFile,
  );
}

void printHelp() {
  stdout.writeln('''
dart_http — a lightweight API request runner

Usage:
  dart_http <method> <url> [options]

Methods:
  get       Send a GET request
  post      Send a POST request
  put       Send a PUT request
  patch     Send a PATCH request
  delete    Send a DELETE request

Options:
  -H, --header    Add a request header (repeatable)
  -b, --body      Request body (JSON string)
  -s, --save      Save response body to a file
  -h, --help      Show this help message

Examples:
  dart_http get https://jsonplaceholder.typicode.com/users
  dart_http get https://api.example.com/me --header="Authorization: Bearer token"
  dart_http post https://api.example.com/posts --body=\'{"title":"Hello"}\'
  dart_http get https://api.example.com/users --save=users.json
  ''');
}

Run it:

dart run bin/dart_http.dart get https://jsonplaceholder.typicode.com/users/1

# → GET https://jsonplaceholder.typicode.com/users/1
# 200 | 87ms | 510b
# ──────────────────────────────────────────────────
# {
#   "id": 1,
#   "name": "Leanne Graham",
#   "username": "Bret",
#   "email": "Sincere@april.biz"
# }

dart run bin/dart_http.dart get https://jsonplaceholder.typicode.com/users --save=users.json
# → GET https://jsonplaceholder.typicode.com/users
# 200 | 143ms | 5.3kb
# ──────────────────────────────────────────────────
# [ ... ]
# Response saved to users.json

dart run bin/dart_http.dart post https://jsonplaceholder.typicode.com/posts \
  --body='{"title":"Hello from dart_http","userId":1}'
# → POST https://jsonplaceholder.typicode.com/posts
# 201 | 312ms | 72b

Adding Color and Polish to Your CLI

The CLIs above are functional, but terminal output can be made significantly more readable with color. The ansi_styles package provides ANSI escape code support for coloring text in the terminal.

Add it to pubspec.yaml:

dependencies:
  ansi_styles: ^0.3.0

Using it:

import 'package:ansi_styles/ansi_styles.dart';

stdout.writeln(AnsiStyles.green('✅ Success'));
stdout.writeln(AnsiStyles.red('❌ Error: something went wrong'));
stdout.writeln(AnsiStyles.yellow('⚠️  Warning: check your config'));
stdout.writeln(AnsiStyles.bold('dart_http — API request runner'));
stdout.writeln(AnsiStyles.cyan('→ GET https://api.example.com/users'));

Apply color intentionally and consistently:

• Green — success states, completed operations

• Red — errors and failures

• Yellow — warnings and non-blocking issues

• Cyan — informational output, URLs, paths

• Bold — headers, tool names, important values

Avoid coloring everything. Color loses meaning when it is everywhere. Use it to draw the user's eye to what actually matters.

Testing Your CLI Tool

CLI tools are testable, and they should be tested. The most reliable approach is to test the logic inside your commands directly — not the terminal output formatting, but the behaviour.

Add test to your dev dependencies if it's not already there:

dev_dependencies:
  test: ^1.24.0

Testing command logic:

import 'package:test/test.dart';

import '../lib/models/task.dart';

void main() {
  group('Task model', () {
    test('copyWith updates isComplete correctly', () {
      final task = Task(
        id: 1,
        title: 'Write tests',
        priority: 'high',
        createdAt: DateTime.now(),
      );

      final completed = task.copyWith(isComplete: true);

      expect(completed.isComplete, isTrue);
      expect(completed.title, equals('Write tests'));
      expect(completed.id, equals(1));
    });

    test('toJson and fromJson round-trips correctly', () {
      final task = Task(
        id: 2,
        title: 'Ship the tool',
        priority: 'normal',
        createdAt: DateTime.parse('2025-01-01T00:00:00.000'),
      );

      final json = task.toJson();
      final restored = Task.fromJson(json);

      expect(restored.id, equals(task.id));
      expect(restored.title, equals(task.title));
      expect(restored.priority, equals(task.priority));
    });
  });
}

Testing the headers parser:

import 'package:test/test.dart';

import '../lib/utils/headers_parser.dart';

void main() {
  group('parseHeaders', () {
    test('parses a single header correctly', () {
      final result = parseHeaders(['Authorization: Bearer mytoken']);
      expect(result['Authorization'], equals('Bearer mytoken'));
    });

    test('parses multiple headers', () {
      final result = parseHeaders([
        'Authorization: Bearer token',
        'Accept: application/json',
      ]);
      expect(result.length, equals(2));
      expect(result['Accept'], equals('application/json'));
    });

    test('ignores malformed headers without a colon', () {
      final result = parseHeaders(['malformed-header']);
      expect(result.isEmpty, isTrue);
    });
  });
}

Run your tests:

dart test

Deploying and Distributing Your CLI

Building a CLI tool is half the work. Getting it into the hands of developers is the other half. There are five distribution paths available, each suited to a different use case.

Mode 1: pub.dev — Public Package Distribution

Publishing to pub.dev makes your tool installable by anyone in the Dart and Flutter community with a single command.

Prepare your package:

Your pubspec.yaml needs to be complete:

name: dart_http
description: A lightweight API request runner for Dart developers.
version: 1.0.0
homepage: https://github.com/yourname/dart_http

environment:
  sdk: '>=3.0.0 <4.0.0'

executables:
  dart_http: dart_http

The executables block is critical. It tells pub.dev which script in bin/ to expose as a runnable command.

You also need:

• README.md — what the tool does, how to install it, usage examples

• CHANGELOG.md — version history

• LICENSE — an open source license (MIT is standard)

Validate before publishing:

dart pub publish --dry-run

This runs all validation checks without actually publishing. Fix any warnings before proceeding.

Publish:

dart pub publish

You will be prompted to authenticate with your pub.dev account. Once published, your tool is available globally:

dart pub global activate dart_http
dart_http get https://api.example.com/users

Mode 2: Local Path Activation

For internal team tools that you don't want to publish publicly, activate directly from a local or cloned repository:

dart pub global activate --source path /path/to/dart_http

Any developer on the team clones the repo and runs this command once. The tool is then available globally in their terminal without needing a pub.dev publish.

This is the right distribution mode for:

• Internal company tooling

• Tools that depend on private packages

• Work-in-progress tools shared within a team before a public release

Mode 3: Compiled Binary via GitHub Releases

Dart can compile to a self-contained native executable — no Dart SDK required on the target machine. This makes your tool accessible to developers outside the Dart ecosystem.

Compile:

# macOS
dart compile exe bin/dart_http.dart -o dist/dart_http-macos

# Linux
dart compile exe bin/dart_http.dart -o dist/dart_http-linux

# Windows
dart compile exe bin/dart_http.dart -o dist/dart_http-windows.exe

The compiled binary is fully self-contained. Copy it to any machine and run it — no Dart installation needed.

Automate with GitHub Actions:

Create .github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v3

      - uses: dart-lang/setup-dart@v1
        with:
          sdk: stable

      - name: Install dependencies
        run: dart pub get

      - name: Compile binary
        run: |
          mkdir -p dist
          dart compile exe bin/dart_http.dart -o dist/dart_http-${{ runner.os }}

      - name: Upload binary to release
        uses: softprops/action-gh-release@v1
        with:
          files: dist/dart_http-${{ runner.os }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Every time you push a version tag (v1.0.0), GitHub Actions compiles binaries for all three platforms and attaches them to the GitHub Release automatically.

Write an install script:

#!/usr/bin/env bash
set -euo pipefail

VERSION="1.0.0"
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
BINARY="dart_http-$OS"
INSTALL_DIR="/usr/local/bin"

curl -L "https://github.com/yourname/dart_http/releases/download/v\(VERSION/\)BINARY" \
  -o "$INSTALL_DIR/dart_http"

chmod +x "$INSTALL_DIR/dart_http"
echo "dart_http installed successfully"

Developers install it with:

curl -fsSL https://raw.githubusercontent.com/yourname/dart_http/main/install.sh | bash

Mode 4: Homebrew Tap

Homebrew is the standard package manager for macOS and is widely used on Linux. A Homebrew tap makes your tool installable with brew install — the most familiar installation pattern for macOS developers.

Create your tap repository:

Create a new GitHub repository named homebrew-tools (the homebrew- prefix is required by Homebrew's naming convention).

Write the formula:

Create Formula/dart_http.rb in that repository:

class DartHttp < Formula
  desc "A lightweight API request runner for the terminal"
  homepage "https://github.com/yourname/dart_http"
  version "1.0.0"

  on_macos do
    url "https://github.com/yourname/dart_http/releases/download/v1.0.0/dart_http-macOS"
    sha256 "YOUR_SHA256_HASH_HERE"
  end

  on_linux do
    url "https://github.com/yourname/dart_http/releases/download/v1.0.0/dart_http-Linux"
    sha256 "YOUR_SHA256_HASH_HERE"
  end

  def install
    bin.install "dart_http-#{OS.mac? ? 'macOS' : 'Linux'}" => "dart_http"
  end

  test do
    system "#{bin}/dart_http", "--help"
  end
end

Generate the SHA256 hash for each binary:

shasum -a 256 dist/dart_http-macOS

Install from the tap:

brew tap yourname/tools
brew install dart_http

When you release a new version, update the url and sha256 values in the formula and push the change. Users run brew upgrade dart_http to update.

Mode 5: Docker

Docker distribution is best suited for CI environments, teams that standardise on containers, or tools with complex dependencies.

Write a Dockerfile:

FROM dart:stable AS build

WORKDIR /app
COPY pubspec.* ./
RUN dart pub get

COPY . .
RUN dart compile exe bin/dart_http.dart -o /app/dart_http

FROM debian:stable-slim
COPY --from=build /app/dart_http /usr/local/bin/dart_http

ENTRYPOINT ["dart_http"]

This uses a multi-stage build: the first stage compiles the binary using the Dart SDK image, and the second stage copies only the binary into a minimal Debian image. The final image has no Dart SDK — just the compiled binary.

Build and run:

docker build -t dart_http .
docker run dart_http get https://jsonplaceholder.typicode.com/users/1

Publish to Docker Hub:

docker tag dart_http yourname/dart_http:1.0.0
docker push yourname/dart_http:1.0.0

Users can then run your tool without installing anything locally:

docker run yourname/dart_http get https://api.example.com/users

Choosing the Right Distribution Mode

For most tools, the practical recommendation is:

• Start with pub.dev if your audience is Dart developers

• Add compiled binary + GitHub Releases once you want broader adoption

• Add a Homebrew tap when macOS developers start asking for it

• Use Docker only when it is already part of your team's workflow

Conclusion

You've gone from understanding what a CLI is to building three progressively complex tools and distributing them across five different channels.

The foundational skills – args, stdin, stdout, stderr, exit codes, file I/O, and process spawning – are the same building blocks that tools like flutter, git, and dart themselves are built on. Everything else is composition.

The three CLIs we built (Hello CLI, dart_todo, and dart_http) each introduced a new layer: raw Dart fundamentals, the args package with JSON persistence, and real-world HTTP interaction. The distribution section ensures that whatever you build next, you have a clear path to getting it in front of the developers who will use it.

Dart is a powerful language for CLI development. Its strong typing, async support, native compilation, and pub.dev ecosystem make it a serious choice for building developer tooling, not just mobile apps.

The next step is building something that solves a real problem for you or your team, and shipping it.

Happy coding!!

The problem only showed up when I checked which authentication middleware the agent had imported.

Our codebase had two: a v1 middleware backed by MongoDB and a v2 middleware backed by MySQL, which we had spent the previous quarter migrating.

New endpoints were supposed to use v2. The agent had used v1 for all three. Tests passed because user records still existed in both databases (that was the point of the migration), and the v1 middleware happily authenticated them. The code worked. But every new endpoint we shipped was reinforcing the legacy auth path we had just spent a quarter trying to retire.

I caught it on the second read. Twenty minutes after the comments, the engineer fixed it and reopened the PR. The third reviewer probably wouldn't have caught it. The migration timeline lived in a Slack thread from six months earlier. The rule that "new endpoints use v2" lived in my head.

This kind of catch is the slow-burn version of why AI changed my job as a tech lead. Code generation got faster. My review queue got longer. The hardest reviews were the ones where everything looked right, and the only thing wrong was something that lived in the team's collective memory rather than in the diff.

This handbook is about what we did to fix that. It's the story of how we went from drowning in clean-looking PRs to running a custom AI PR reviewer that catches a meaningful share of these mistakes before any human is pulled in. The fix turned out to be less about buying a better tool and more about moving the team's memory into a place the AI could actually read.

The lessons should transfer whether your team uses Claude Code, Cursor, Cline, GitHub Copilot, or any combination. The structure matters more than the tool.

Table of Contents

• The Old Bottleneck, and the One AI Created

• What the New Review Work Actually Looks Like

• Why I Did Not Just Buy a Tool

• The Realisation: Move the Rules Into the Codebase

• Two Files That Changed Everything: AGENTS.md and CLAUDE.md

• Where Per-Service Memory Files Earn Their Keep

• What This Looks Like on Disk

• Generated Documentation as a Side Effect

• Building the PR Review Command

• Guardrails: Read-Only by Default

• The Compounding Loop That Made the Real Difference

• Starting From Zero on an Existing Project

• What Still Needs Human Review

• A Two-Week Setup Plan

• What Is Working, What I Am Still Improving

• Sources

The Old Bottleneck, and the One AI Created

To understand why this fix was needed, it helps to remember what reviewing code looked like a couple of years ago.

Back then, the slow part was upstream of the PR. A ticket would land, and before anyone could open a branch, there was a long preamble of context-gathering.

Junior engineers needed time to understand what the change was for. Senior engineers had to explain business rules and architectural decisions. Tickets sat in "ready" columns for days while someone with the right context made themselves available. Then the writing itself took time, because typing real code is slower than typing comments about it.

That bottleneck mostly dissolved when the team got serious about AI-assisted development. Engineers used the agent to read the codebase, ask clarifying questions, draft an implementation plan, and produce a working branch in hours instead of days. Tickets moved through the queue faster. Junior engineers shipped more without blocking on senior availability. From the outside, this looked like an unambiguous win.

But the bottleneck didn't disappear. It moved.

Within a few weeks of widespread AI adoption, my review queue had doubled. Then tripled. Engineers were opening PRs faster than I could read them.

The PRs themselves looked clean: well-formatted, with sensible variable names, passing tests, and AI-generated descriptions that read better than most human-written ones.

On the surface, this was great. In practice, it was creating a different kind of pain. I was the senior engineer who knew which patterns mattered and which paths through the codebase were the right ones, and I was the bottleneck. The team's velocity was now capped by my reading speed.

The CircleCI 2026 State of Software Delivery report confirmed I was not alone. Drawing on more than 28 million CI workflow runs across over 22,000 organisations, the report showed feature branch throughput had grown 59% year over year, the largest jump CircleCI had ever measured. Main branch throughput, where code actually gets promoted to production, fell by 7% for the median team in the same period. Build success rates dropped to 70.8%, the lowest in five years.

The pattern was consistent across the industry. AI accelerated writing. The rest of the system absorbed the cost.

So the question for me, as a tech lead, became concrete: how do I unblock myself without lowering the bar?

What the New Review Work Actually Looks Like

Before I explain the fix, it helps to know what kinds of issues were actually piling up. They weren't the dramatic kind. None of them would crash production. They were small, recurring, and looked plausible at a glance.

Take the simplest case I kept catching. An engineer would ask the agent to add a delete button on a new screen. The button needed to call our existing backend delete endpoint. Instead of reusing the hook the team already had for that endpoint, the agent would write the fetch call inline.

The code worked. The tests passed. But a week later, when someone changed the backend response shape, only one of the two call sites got updated.

That kind of duplication doesn't show up in a code review unless the reviewer happens to remember that a hook exists.

Another example I saw constantly: the agent comparing a status field against the literal string "completed" instead of using the Status.Completed enum that the rest of the services used. The code ran. The tests ran. The next refactor of the enum quietly skipped the file. After a few days, someone would spend half a day debugging a state machine that was working fine until the agent's literal silently fell out of sync.

These were two-minute fixes once spotted, but spotting them took me a reasonable time per PR. The friction wasn't the difficulty. It was the repetition.

The pattern repeated across larger problems, too.

I once asked an agent to build an event creation wizard. The wizard needed several dropdowns and one new component.

We have a design system folder where shared UI components live, and the rule on the team is simple: check there first, and if you build something new, register it there.

The agent had no way to know that. It only loaded the wizard's own files, so it never opened the design system folder. It generated brand new dropdowns inline, with APIs that were almost identical to the ones we already had. The new component went straight into the wizard rather than into the design system. CI passed. The wizard worked. We caught the duplication in human review, but it was the kind of catch that depended entirely on a reviewer who happened to know the design system existed.

The same pattern hit in one of the repos I was looking at for backend architecture. Backend follows a strict four-layer pattern: route, controller, app, repo. Controllers must never call repository functions directly. That rule keeps authorisation centralised, business logic testable, and database concerns isolated.

One PR I reviewed had the agent calling repo functions straight from a controller, skipping the app layer entirely. The code worked. The tests passed because the agent had also written tests against the new shape. But it broke a discipline the team had spent years building. If that PR had landed, the next AI-assisted PR could have used it as a template, and the layering would have eroded one diff at a time.

The common thread is that all of these mistakes had something written down somewhere, in code, in a Slack thread, in a senior engineer's head, that would have prevented them. The information existed. The agent just couldn't see it.

Why I Did Not Just Buy a Tool

The obvious next move was to install one of the AI PR reviewers that flooded the market in 2026.

I evaluated several. Anthropic launched Claude Code Review in March 2026, billed on token usage and averaging \(15 to \)25 per review. CodeRabbit Pro charges \(24 per developer per month on annual billing, or \)30 per developer per month on monthly billing, with seats counted against developers who actually open PRs. Greptile in March 2026 moved to a base-plus-usage model at $30 per seat per month, including 50 reviews, after which each additional review costs a dollar. GitHub announced that all Copilot plans will transition to usage-based billing on June 1, 2026, with code reviews consuming both AI Credits and GitHub Actions minutes from that date.

For a small team with low PR volume, none of these is a dealbreaker. For a larger team running heavy AI-assisted development, the costs compound fast. A 10-person team running five PRs each per day blows through Greptile's included reviews in a single week. CodeRabbit Pro at \(24 per seat scales linearly with developers. The premium Claude Code Review at \)15 to $25 per PR is the most expensive option per review by an order of magnitude.

I looked at the cost numbers, but cost wasn't actually the deciding factor. The deciding factor was that none of these tools would have caught the problems I just listed.

A generic reviewer wouldn't have caught the v1/v2 middleware. It had no way to know v2 was the canonical path. A generic reviewer wouldn't have caught the duplicate dropdowns. It had no way to know our design system existed. A generic reviewer wouldn't have caught the bypassed architecture. It had no way to know that controllers must not call repositories.

The information that lets a reviewer flag any of these is exactly the information that lives in the team's head, not in any tool's default prompt.

The better-rated tools support custom rules, and that's where I started to see the real shape of the problem. Once you are configuring custom rules, you've already accepted that the value is in the rules. The tool is just whatever runs them.

This raised a different question: if the rules are the product, why pay per seat or per review for someone else's wrapper around them?

This is what made me change direction.

The Realisation: Move the Rules Into the Codebase

Once I started thinking of the rules as the product, the path forward got clearer.

I asked myself a simple question: what was I actually doing in code review that the AI was not? The answer turned out to be the same thing, over and over. I was typing review comments that captured a piece of the team's memory.

"Use the Status enum, not a string literal." "There is already a hook for this in /hooks/useDeleteItem." "Controllers must not import from the repo layer; route this through the app layer." "Check the design system folder before creating new components."

Each of those comments was knowledge that lived in my head and arrived in the codebase one PR comment at a time. None of it was available to the agent the next time it generated a similar PR.

So the fix was not to buy a smarter reviewer. The fix was to write the rules down in a place every agent on the team would read before any review happened.

If I had typed "use the enum, not a literal" three times in three different PRs, that was a rule the agent should know about from now on. If I had pointed at the design system folder for the fourth time, that was a rule. If I had explained the four-layer architecture twice in PR comments, that was a rule.

I needed somewhere to put these rules. That turned out to be a less obvious decision than I expected.

Two Files That Changed Everything: AGENTS.md and CLAUDE.md

If you start looking into how to give an AI agent a persistent project context, you run into two competing conventions almost immediately.

The first is AGENTS.md, an open standard that has gathered real momentum. According to InfoQ, by mid-2025, the format had already been adopted by more than 20,000 GitHub repositories and was being positioned as a complement to traditional documentation: machine-readable context that lives alongside human-facing files like README.md.

The standard's own site reports it is now used by more than 60,000 open-source projects and has moved to stewardship under the Agentic AI Foundation, which sits inside the Linux Foundation. The format is supported by OpenAI Codex, GitHub Copilot, Google Gemini, Cursor, and Windsurf, among others.

The second is CLAUDE.md, which is Anthropic's convention for Claude Code. The Claude Code documentation describes two complementary memory systems: CLAUDE.md, where you write the persistent context yourself, and an auto-memory mechanism that lets Claude save its own notes from corrections and observed patterns. By default, Claude Code reads CLAUDE.md, not AGENTS.md.

This split mattered for us because half the team uses Claude Code and the other half uses Cursor. We had two practical options: maintain both files with the same content (and accept the duplication), or symlink one filename to the other so both ecosystems read the same source of truth. We went with the symlink. It's one less thing to drift.

The next question was what to actually put in the file. After a few iterations, here's the shape that worked. Think of it as a briefing document for a new engineer who has read no code and seen no Slack threads. The minimum content was:

• The tech stack (languages, frameworks, package manager)

• The project structure, especially important for our monorepo

• Where shared utilities, components, and helpers live, and the rule that new code should reuse them before creating new versions

• Architectural patterns the project follows, with file path examples

• Anti-patterns and what to do instead

• Test conventions and where good examples live

• Pointers to deeper documentation when more detail is needed

Two practical rules emerged from the first month of using these files.

Keep them lean: There is a counterintuitive failure mode with long instruction lists: the agent doesn't just skip the new ones at the bottom. The average compliance across all of them drops. A bloated memory file becomes a memory file that the agent skims. If a section runs more than a paragraph or two, move it to a separate document and link to it.

Phrase rules as imperatives, not aspirations: "Controllers must not call repositories. Route through the app layer." beats "Try to keep controllers thin." The first is testable. The second is decorative.

That was the entry point. But a single root-level file was not enough for a monorepo with multiple services and frontends, which led to the next decision.

Where Per-Service Memory Files Earn Their Keep

A single AGENTS.md at the root of a monorepo collapses under its own weight pretty quickly. Each service in our codebase has its own architecture, conventions, and business rules. Trying to fit all of that into one file produced a long document that the agent treated as background noise, and we were back to the bloat problem from the previous section.

The pattern that worked: every service or app gets its own AGENTS.md at its root, and the project-level AGENTS.md becomes an index that points to them.

A per-service AGENTS.md covers things like:

• The architecture for this service (the four-layer pattern, the directory layout)

• Naming conventions specific to this service

• Test patterns and where good examples live

• Business rules that this service is responsible for

• Inter-service contracts and what other services consume from this one

• Pointers to deeper docs in docs/

• A "Lessons learned" section, which I'll come back to in the section on the compounding loop

The same lean rule applies. Keep it short, point at examples, and phrase guidance as imperatives.

The reason this works mechanically is that the agent loads the right files for the work at hand. When an engineer asks the agent to change something in backend/, the agent reads the project-level AGENTS.md, sees that work in backend/ should be guided by backend/AGENTS.md, and loads that file. It doesn't load the frontend's AGENTS.md, because that work is somewhere else. The context window stays focused on what's relevant.

Without this split, you have two bad options. Either you put everything in the root file, where the agent ignores most of it, or you put nothing in the root file, where the agent has no team context at all. The per-service split gives you both depth and signal.

But these files only work if the deeper docs they point to actually exist, which is where the next piece of the system came in.

What This Looks Like on Disk

Before going further, it helps to see the whole structure laid out. Here's the shape we settled on for our monorepo. The exact folder names follow Claude Code's conventions. If you use Cursor, it would be .cursor/, and if you use Cline, it would be .clinerules – but the shape transfers directly.

project-root/
├── AGENTS.md                       # symlink to CLAUDE.md
├── CLAUDE.md                       # root memory file
├── README.md                       # human-facing project readme
│
├── .claude/                        # tool-specific config folder
│   ├── README.md                   # explains the .claude/ layout
│   ├── settings.json               # permissions and guardrails
│   ├── agents/                     # specialised subagents (optional)
│   ├── commands/                   # slash commands engineers run
│   │   ├── review-pr.md            # the PR review command
│   │   └── plan-feature.md         # implementation plan command
│   ├── hooks/                      # lifecycle hooks (optional)
│   ├── pr-rules/                   # rule files for PR review
│   │   ├── common.md               # rules that apply to every PR
│   │   ├── frontend.md             # rules for frontend changes
│   │   ├── backend.md              # rules for backend changes
│   │   ├── service-a.md            # rules for service-a
│   │   └── service-b.md            # rules for service-b
│   └── skills/                     # reusable workflows
│
├── frontend/
│   ├── AGENTS.md                   # frontend conventions
│   ├── docs/
│   │   ├── overview.md
│   │   ├── architecture.md         # routing, state, data layer
│   │   ├── design-system.md        # design system reference
│   │   └── testing.md              # test conventions
│   └── src/
│
├── backend/
│   ├── AGENTS.md                   # the four-layer pattern
│   ├── docs/
│   │   ├── overview.md
│   │   ├── architecture.md         # route -> controller -> app -> repo
│   │   ├── auth.md                 # v1 vs v2 middleware
│   │   ├── business-rules.md
│   │   └── integrations.md
│   └── src/
│
├── service-a/
│   ├── AGENTS.md
│   ├── docs/
│   │   ├── overview.md
│   │   ├── business-rules.md
│   │   └── integrations.md
│   └── src/
│
└── service-b/
    ├── AGENTS.md
    ├── docs/
    │   ├── overview.md
    │   ├── business-rules.md
    │   └── integrations.md
    └── src/

A few things worth pointing out:

The .claude/ folder uses standard subfolder names: commands, agents, hooks, skills. These follow Claude Code's plugin model, but most modern AI coding tools have similar slots. Following the conventions makes the structure recognisable to anyone on the team and lowers the cost of switching tools later.

The pr-rules/ folder isn't a standard convention. It's a folder we created to hold per-area review rules that the PR review command loads selectively. You don't have to call it pr-rules – the name matters less than having one place where review rules live.

Each service has its own AGENTS.md plus a docs/ folder. The root AGENTS.md is short and acts as an index. It tells the agent things like "if you touch files in backend/, also read backend/AGENTS.md first." The per-service file then points at the deeper docs as needed.

Generated Documentation as a Side Effect

Setting up per-service AGENTS.md files surfaced a problem I had been quietly avoiding. Most of our services didn't have decent documentation. Not API reference material, which lives in code, but the higher-level "what does this service do, what business rules does it enforce, what does it consume and produce" information that lives in nobody's head except the original author's.

The honest reason was that writing this kind of documentation by hand had never paid back the time it took. By the time the doc was finished, half of it was already stale.

So I tried something I wouldn't have considered earlier. I used the AI itself to generate a first draft for each service. I pointed the agent at each service's code and asked it to produce a docs/ folder with a specific structure: an overview, a list of business rules, an integrations document, a domain model, and any quirks worth knowing. The agent read the code, traced the call paths, and wrote a draft.

I then reviewed the output by hand, corrected the things it got wrong, and committed the result. The first drafts were 70-80% correct. The remaining 20-30% was where the agent had made plausible but wrong inferences, and those were exactly the cases where human review mattered.

The generated docs ended up serving two audiences. The agent uses them when reasoning about changes, which means it has real context for the service it's touching rather than guessing from local files. And new engineers use them on their first day, which has cut our onboarding time noticeably.

We used to write onboarding documents that drifted out of date within months. These docs stay closer to current because the agent reads them on every PR, and any drift gets surfaced when the agent gives wrong advice based on stale information.

The pattern that works is to keep the per-service AGENTS.md short and pointing at the docs, rather than duplicating their content. AGENTS.md is the always-loaded index. docs/ holds the details. The agent loads the relevant doc on demand when the task calls for it.

With the rules in place and the docs in place, I had everything I needed to build the actual reviewer.

Building the PR Review Command

This is the piece that most directly unblocked my queue.

This command didn't appear out of nowhere. It started as the checklist I was running through in my head every time I opened a PR. I was reviewing every change manually, leaving the same comments, flagging the same patterns. So I wrote that checklist down, expanded it with references to the per-service docs for the harder rules, and turned it into a command anyone on the team could run.

Then I handed it to the engineers and changed the rule: run this on your own branch before marking the PR ready for review. That single shift moved the work from after the PR was opened to before. Engineers now catch 90-95% of the blockers, improvements, and nice-to-haves on their own machine, fix them locally, and only then push the change.

The PR description includes the AI's summary, so when anyone opens the PR, they can see the reviewer's green signal at the top before even reading the diff.

GitHub stays clean. The conversation on the PR becomes about the things that actually need a human, not the recurring stuff the team already knows how to fix.

The command lives in .claude/commands/review-pr.md. Here's a generalised version. Your tool's command structure may differ, but the shape is what matters.

# Review PR

Review the current branch's PR. Be direct. Cite `file:line`. Surface real issues,
no padding.

## 1. Scope the diff

Run, in order:

    gh pr view --json number,title,body,headRefName 2>/dev/null || true
    git fetch origin main
    git log --no-merges origin/main..HEAD --oneline
    git diff origin/main...HEAD --stat
    git diff origin/main...HEAD

Read the PR body. Note the stated intent. Every change should trace to it. Flag
anything that does not.

Use `...` (three dots) for the diff. It compares against the merge base and
excludes commits brought in by merging main.

## 2. Load rules

Always read `.claude/pr-rules/common.md`.

Then read the per-area file for each workspace touched in the diff:

| Workspace path | Rules file                      |
| -------------- | ------------------------------- |
| `frontend/**`  | `.claude/pr-rules/frontend.md`  |
| `backend/**`   | `.claude/pr-rules/backend.md`   |
| `service-a/**` | `.claude/pr-rules/service-a.md` |
| `service-b/**` | `.claude/pr-rules/service-b.md` |

For non-trivial changes, follow doc pointers inside the rules files (for
example, `backend/AGENTS.md`, `backend/docs/architecture.md`).

Apply every entry under each file's "Lessons learned" section as a check.

## 3. Output

Use exactly this format.

    ## Summary
    <one paragraph: what the PR does, whether it matches the stated intent>

    ## Blocking
    - [file:line] issue, why it blocks

    ## Should fix
    - [file:line] issue

    ## Nice to have
    - issue

    ## Verified
    - what was checked and looks good

If nothing blocks, say so. Do not manufacture concerns.

If you find an issue worth remembering for future PRs, suggest the bullet to
add to the relevant rules file's "Lessons learned" section. Do not edit the
rules file yourself, leave that to the human.

A few of the design choices in this command turned out to matter more than I expected.

The structured output format (Summary, Blocking, Should fix, Nice to have, Verified) keeps the review easy to scan and easy to paste into a PR description. The "Verified" section is the most underrated of the five: it tells the human reviewer what the AI already checked, so they can spend their attention elsewhere. Without it, the human reviewer ends up doing the same checks twice.

The instruction to be direct and stop padding does real work. Without it, AI reviewers tend to manufacture concerns to look thorough, which trains engineers to skim past the bot. Telling it explicitly to say "nothing blocks" when nothing blocks made the signal-to-noise ratio of the output much better.

The "suggest a bullet for the rules file" instruction at the end is the heart of the whole system, and I'll explain why in the section on the compounding loop. The key constraint here is that the agent suggests the bullet but doesn't commit to it. A human evaluates whether it's general enough to be a rule, and only then adds it to the file. That manual step is what keeps the rules sharp instead of bloated.

With each PR, if humans fix something or the AI suggests something, you keep adding those to your MD files and keep improving your agents for the future. The result compounds quickly.

One more thing here: the diff-scoping commands are all read-only. The command shouldn't be able to push, edit PRs, or close anything. Which is the next piece of the system.

Guardrails: Read-Only by Default

Giving an AI agent broad permissions on your codebase is a security incident waiting to happen. Even if you trust the model to behave, an LLM occasionally does unexpected things, and a fast-moving agent on an unrestricted shell can cause damage in seconds.

The fix is a settings.json (in Claude Code – other tools have their own equivalents) at the root of .claude/ that explicitly declares what the agent can and can't do. The deny list matters more than the allow list, and a good one is organised around four categories of risk.

The first is secrets and configuration. Any read against anything that appears to be a credential is blocked. That covers .env files of every variant (.env, .env.local, .env.production, .env.test, and so on), .npmrc, .netrc, .pgpass, id_rsa, id_ed25519, *.pem, *.key, *.p12, **/credentials.json, **/secrets.json, **/.aws/**, **/.ssh/**, **/.gcloud/**, and **/.kube/**. Environment dumps are blocked too: env, printenv, set, export. The agent has no legitimate reason to read or echo any of these, ever.

The second is destructive Git operations. The agent can read Git history but can't rewrite or push it. Blocked: git push, git commit, git revert, git cherry-pick, git merge, git rebase, git reset --hard, git tag. Allowed: git fetch, git status, git log, git diff, git show, git branch, git rev-parse, git merge-base, git config --get.

The third is write operations on PRs and issues. The agent can read your GitHub state but can't act on it. Blocked: gh pr create, gh pr edit, gh pr merge, gh pr close, gh pr comment, gh pr review, gh issue create, gh issue edit, gh issue close, gh issue comment, gh release create, gh repo create, gh repo edit, gh repo delete. Allowed: gh pr view, gh pr list, gh pr diff, gh pr checks, gh issue view, gh issue list, gh release view.

The fourth is workflow and automation control. These are the surfaces where a compromised or misled agent could do the most damage. Blocked: gh workflow run, gh run rerun, gh run cancel, gh secret, gh variable, gh auth, gh ssh-key, gh gpg-key, and the unrestricted gh api.

For shell commands the agent legitimately needs to run, like build and test commands, allowlist specific patterns: pnpm test, pnpm lint, pnpm format:check, pnpm build, pnpm vitest. Anything outside the allowed list requires human confirmation. These are your own settings – I've just mentioned what I prefer.

The pattern is simple: read-only by default, write-allowed only for the specific commands you have explicitly approved. The agent can investigate, plan, and recommend. It can't ship.

With the structure in place and the guardrails set, the system started doing its job. What I didn't expect was how much better it would get over the months that followed.

The Compounding Loop That Made the Real Difference

When we started, the AI reviewer was useful but not transformative. It caught some obvious issues, missed plenty of subtle ones, and produced a fair amount of noise.

The first month, my review burden dropped by 35%. The time I was spending on PR checking was reduced to 1/3, almost. Decent, not life-changing.

What changed over time wasn't the tool. It was the rules.

Every time a PR creator and reviewer caught something the AI had missed, we were adding bullets to the relevant rules file. Every time the AI flagged something useful that turned out to be a recurring pattern, the agent's own suggestion at the end of the review went into the file.

After a few days, the rules files had grown into something that captured a meaningful fraction of the team's collective review knowledge, written down in a place every agent on the team would read.

The catch rate went up. The noise went down because the rules also said what was acceptable and what we already considered solved. New engineers stopped getting the same comments on their first three PRs because the AI caught the comments first. Engineers joining the team didn't have to absorb the conventions through six months of review feedback. They installed the project, opened it in their editor, and the agent already knew.

This is the part most teams miss when they evaluate AI PR review tools. They look at the catch rate today and decide whether the tool is worth the price. The catch rate today isn't the right number. The right number is what the catch rate looks like in six months, after the rules file has absorbed every recurring mistake your team has made.

A single rule written down today saves a small amount of review time. Over a hundred PRs, it saves more. After a year, the rules file is a written-down version of a tech lead's accumulated taste. We've switched between Claude Code, the GitHub Copilot CLI, and Cursor for various tasks during this period. The AI tool changes, but the rules file in the repo stays the same.

The discipline that makes this work is treating the rules file as living documentation. Every recurring review comment is a candidate for promotion into the file. If you catch yourself typing the same feedback in two different PRs, that's a rule that belongs in pr-rules/. The "suggest a bullet" instruction in the review command is what makes this practical: the AI does the typing, the human does the deciding.

This is also what made me realise the system was worth the time it took to set up. The PR review command, on its own, is useful but unremarkable. The compounding loop is what turns it into infrastructure.

Starting From Zero on an Existing Project

If you've read this far and feel like the gap between your project and what I just described is a sprint of work, that's the most common reaction. It's also not correct.

The blank AGENTS.md is intimidating, especially on an existing codebase. You know your team has a thousand conventions, and writing a thousand rules sounds like a project that takes weeks before it produces any value.

The honest answer is that you can't write all the rules up front, and you shouldn't try. The first version of any of these files should take an afternoon, not a sprint.

Here's how I would actually start.

Run /init (or your tool's equivalent). In Claude Code, /init scans the project, infers the obvious shape (language, framework, entry points, build commands), and writes an initial CLAUDE.md. The output is a starting point, not a finished file. Read it, delete most of what it generates, and keep the bones.

Then add three things, each one bullet long.

First, an architecture rule. Pick the single most important convention your team enforces. For us, that was the four-layer pattern. The bullet was: "Controllers must not call repository functions directly. They must go through the app layer."

Second, a discoverability rule. Pick the single most important shared resource the team has, the one new code is most likely to duplicate. For us, that was the design system. The bullet was: "Before creating a new UI component, check /src/design-system/ first."

Third, a "do not touch" rule. Pick the single most dangerous file or area in the codebase. Auth, billing, or migrations whichever has the most production risk. The bullet was: "Do not modify files in /auth/ without human approval."

That's enough to start. Three rules, ten minutes of writing, and most of your team's recurring AI mistakes start to drop.

If even three rules feels like too much, start with one. Pick a single line that matters in your codebase and write it down.

"No any types in TypeScript." "Always use the enum, never compare against the string literal." "Run the linter before opening a PR." It doesn't have to be sophisticated. It doesn't have to cover edge cases. It just has to capture one piece of judgement that lives in your head today and would otherwise stay there.

Tomorrow, add another. The first week, you might catch 5% of the recurring mistakes. By 20 or 30 PRs in, you might catch 20-30%. The rules file doesn't need to be impressive on day one. It needs to exist and keep growing.

This is the compounding effect I'll come back to soon, and it's the reason this approach works on real projects rather than just in theory.

From there, the file grows the same way it would grow for any team. Every review catch becomes a candidate rule. After a few weeks, you have ten or fifteen rules. After a few months, you have a real review system.

The mistake is trying to write the perfect file on day one. The right file is the one you start with and keep editing.

What Still Needs Human Review

This system doesn't replace human review, and it shouldn't be allowed to.

The AI reviewer catches what the rules describe, plus a fair number of obvious things it would have spotted anyway. It doesn't catch problems that depend on context the rules don't capture. It doesn't catch product judgement. It doesn't catch the question of whether the change should have been built at all.

It also has an important blind spot when reviewing AI-authored code. The reviewer shares the same training data and reasoning patterns as the agent that wrote the code. If the original agent missed the v1/v2 distinction because it had no way to see the migration timeline, an AI reviewer reading the same diff has the same problem. Two AIs in a review loop are not two independent reviewers. They share blind spots.

That is why the AI reviewer in this setup never approves a PR. It produces a structured review that goes into the PR description. A human still reads the change and approves it. The AI is the first pass, not the gate.

Accountability also has to live with a human. When something the AI approved breaks production, someone has to own the post-mortem and decide what changes are needed for next time. The AI can't be that person. What it can do, well, is reduce the stack of small mistakes a human reviewer has to find before they get to the harder questions.

A Two-Week Setup Plan

If you want to set this up for your own team, here's a concrete plan that fits in a couple of weeks. None of this needs to happen in a single push.

Day 1: Bootstrap the memory file.

Run /init (or your tool's equivalent) at the root of the project. Read the generated CLAUDE.md (or AGENTS.md). Delete most of it. Keep the tech stack and project structure sections.

Add the three rules from the previous section: one architecture rule, one discoverability rule, and one "do not touch" rule. Decide whether you want both files or a symlink.

Day 2: Add per-service files for your highest-risk areas

Pick the two or three areas of the codebase that change most often or carry the most risk. Add an AGENTS.md to each, following the same lean pattern. Include the architectural pattern for that area, the naming conventions, where to find good test examples, and pointers to any existing docs. Skip anything that doesn't need to be there yet.

Day 3: Set up the directory structure and guardrails

Create a .claude/ folder (or your tool's equivalent) at the root, with commands/ and pr-rules/ subfolders. Add a settings.json with the deny list categories from the guardrails section. Test that the agent can't read a .env file, run git push, or create a PR. If any of those work, fix the settings before doing anything else.

Day 4: Write the PR review command

Adapt the command in this article to your structure. Include the diff scoping, the rule loading, the output format, and the "suggest a new rule" instruction at the end. Run it on a branch you've already merged, and tune the output until it's useful.

Day 5: Run it on real PRs

Have one or two engineers run the command on their next PRs before opening them. Read the output. Note what it caught, what it missed, and what was noise. Add the missing catches to the rules files. The first week is mostly tuning.

Week 2: Roll out and document

Once the command produces useful output reliably, ask the whole team to run it before opening PRs and paste the output into the PR description. Add a short section to your contributing guide explaining the workflow. Set a recurring item in your team's rituals to review the rules files monthly and trim anything that has gone stale.

That gets you to a working system. From there, the maintenance is incremental. Every recurring review comment becomes a candidate rule. Every architectural decision becomes a candidate update to the relevant AGENTS.md. The system improves as a side effect of the work the team is already doing.

What Is Working, What I Am Still Improving

Here's my honest assessment after a few months of running this:

What's Working

My review burden is meaningfully smaller. Engineers fix most of the easy mistakes before I see the PR. The "Verified" section of the AI's output tells me what to skip past. New engineers ramp faster because the conventions live in a place their tooling reads. The rules files have grown into something I would actually use to onboard someone new.

What Isn't Finished

The AI still misses problems that depend on context, and the rules don't capture them. The rules files grow, but they also need pruning, and we haven't been disciplined about that.

We're still figuring out how to handle rules that apply only conditionally. Docs are helping in that case, but we need to keep those up to date. And no system survives a determined engineer who skips the workflow or docs when they're in a rush.

There's no shortcut here. The work is real, ongoing, and mostly about discipline. The discipline is treating your codebase as something the AI needs to learn, and treating every recurring review comment as something that should be written down once instead of typed thirty times. If you're willing to do that, the tools take care of the rest.

If you take three things from this article, take these.

1. First, don't pay for a generic reviewer to do a job your codebase needs to inform. Generic reviewers catch generic problems. Most of your real review work is specific to your team.

2. Second, put the rules in a file the AI reads, not in your head. AGENTS.md, CLAUDE.md, per-service files, per-area rules files. Pick a structure and stick to it.

3. Third, treat every human review catch as a chance to update the rules. The compounding effect over months is the entire point. A review system that improves itself is worth more than any single tool.

That's the system. It took a couple of weeks to build the foundation and a few months for the rules to mature. It costs very little to run, and it has done more for our PR throughput than any tool I evaluated.

Sources

• CircleCI's 2026 State of Software Delivery report, analysing more than 28 million CI workflows from over 22,000 organisations: https://circleci.com/resources/2026-state-of-software-delivery/

• CircleCI's blog post detailing the year-over-year throughput numbers, including the 59% feature branch growth and the main branch decline: https://circleci.com/blog/five-takeaways-2026-software-delivery-report/

• GitHub announcement of Copilot's transition to usage-based billing on June 1, 2026: https://github.blog/news-insights/company-news/github-copilot-is-moving-to-usage-based-billing/

• GitHub changelog confirming Copilot code review will start consuming GitHub Actions minutes on June 1, 2026: https://github.blog/changelog/2026-04-27-github-copilot-code-review-will-start-consuming-github-actions-minutes-on-june-1-2026/

• AGENTS.md, the open standard's official site, including its stewardship under the Agentic AI Foundation and the Linux Foundation: https://agents.md/

• Anthropic's Claude Code documentation on the memory system, including CLAUDE.md, auto memory, and the /init command: https://code.claude.com/docs/en/memory

• Anthropic's Claude Code GitHub Actions documentation, including notes on token-based billing and recommended cost controls: https://code.claude.com/docs/en/github-actions

• CodeRabbit's pricing documentation, confirming the per-developer-per-month seat model: https://docs.coderabbit.ai/management/plans

• Greptile's March 2026 pricing announcement, introducing the base-plus-usage model at $30 per seat per month with 50 included reviews: https://www.greptile.com/blog/greptile-v4

• HumanLayer's write-up on writing a good CLAUDE.md, including data on instruction-following degradation: https://www.humanlayer.dev/blog/writing-a-good-claude-md

And honestly? It was a fair point. You'd write the contract — the interface, the abstract class, the protocol — and then write the implementation. Two files where one would do. That's more surface area, more indirection, and more to maintain.

The Ruby and Rails communities built an entire philosophy around this: convention over configuration, less ceremony, fewer keystrokes. If the framework could infer your intent, why spell it out?

Then AI happened.

I was recently chatting with a CEO about what current-generation software engineers get wrong, and he put it cleanly:

"Abstract interfaces were challenging a few months ago just because it required twice as much code. But with AI, lines of code are free. The reason we still need such constructs is because at some point a human still needs to look at the code. Interfaces reduce the cognitive load."

That framing stuck with me. The cost of writing code has collapsed. The cost of reading it hasn't moved. And that asymmetry changes everything about how you should think about abstraction.

Here's what I mean.

Table of Contents

• Your Brain Is the Bottleneck

• The Greats Already Knew This

• The Economics Have Flipped

• The Data Backs It Up

• The Contrarian Case (And Why It Actually Agrees)

• What This Means for You

• References

Your Brain Is the Bottleneck

This isn't a vibes argument. There's actual neuroscience behind why interfaces help.

In 1988, educational psychologist John Sweller introduced Cognitive Load Theory. A 2022 ACM review covers how it's been applied to computing education since.

The short version: your brain juggles three types of load when processing information. Intrinsic load is the inherent difficulty of the problem itself. Extraneous load is the noise — poorly organized information, unnecessary details, bad naming. Germane load is the good stuff — the mental effort you spend building useful mental models.

Here's the kicker: your working memory can only hold a handful of chunks of information at a time — cognitive scientists typically estimate somewhere between 2 and 6. Not 2 to 6 files, or 2 to 6 classes — 2 to 6 things.

Felienne Hermans explores this in The Programmer's Brain (2021), arguing that design patterns act as chunking aids. When you recognize a Strategy pattern, your brain collapses an entire class hierarchy into a single cognitive unit. The word "Strategy" replaces five classes and their relationships. That's not hand-waving about clean code — that's how human memory actually works.

And we can literally see it on brain scans. In 2021, a team led by Norman Peitek and Janet Siegmund published an fMRI study on program comprehension that won the ACM SIGSOFT Distinguished Paper Award at ICSE.

They put developers in brain scanners and watched what happened when they read code. The finding: semantic-level comprehension — understanding what code does — required measurably less neural activation than bottom-up syntactic parsing — tracing how it does it.

An interface lets you comprehend at the semantic level. UserRepository.findById(id) tells you everything you need to know without opening the implementation. Your brain doesn't need to hold the SQL query, the connection pool logic, the error handling, and the result mapping in working memory simultaneously. The interface compresses all of that into one chunk.

That's not elegance. That's neuroscience.

The Greats Already Knew This

The case for abstraction isn't new. The people who built the foundations of computer science were making this argument before most of us were born.

Dijkstra said it with precision:

"The purpose of abstracting is not to be vague, but to create a new semantic level in which one can be absolutely precise."

Abstraction isn't about hiding things from people who can't handle complexity. It's about creating a level of discourse where you can reason clearly.

David Parnas formalized information hiding in his 1972 ACM paper: "Every module is characterized by its knowledge of a design decision which it hides from all others." He proved that decomposing systems by design decisions (rather than processing steps) produced modules that were both more flexible and easier to understand. Comprehensibility wasn't a bonus — it was the design criterion.

Tony Hoare argued that abstraction is the most powerful tool available to the human intellect — a way to manage complexity by focusing on what matters and ignoring what doesn't. Martin Fowler brought it down to earth:

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."

And then there's John Ousterhout, whose book A Philosophy of Software Design (2018) makes the connection to cognitive load explicit. His central argument: more lines of code can actually be simpler if they reduce cognitive load.

His concept of deep modules — simple interfaces hiding complex implementations — is essentially the argument that interfaces are worth their weight in code. The Unix file system API (open, close, read, write, lseek) is five functions hiding an enormous amount of complexity. That's a deep module. That's the goal.

The Gang of Four put it first in their book for a reason. Page one: "Program to an interface, not an implementation."

None of this is controversial. But it's easy to forget when your AI tool just generated 200 lines of perfectly functional inline code in three seconds.

The Economics Have Flipped

Here's where the CEO's insight becomes an economic argument.

The historical case against interfaces was always about writing cost. Interfaces meant more code to write, more files to create, more boilerplate to maintain. The entire dynamic typing movement — Python, Ruby, JavaScript — was partly a reaction to the ceremony that languages like Java imposed. Convention over configuration. Don't Repeat Yourself. Less is more.

But ask yourself: what exactly is the cost of writing boilerplate now?

GitHub's 2022 controlled study found that developers using Copilot completed tasks 55% faster. The boilerplate that used to justify skipping interfaces — the extra file, the type definitions, the method signatures — takes seconds to generate. The writing cost of an interface has effectively collapsed to zero.

But again, the reading cost hasn't budged.

Robert C. Martin argued in Clean Code (2008) that developers spend far more time reading code than writing it — an observation he framed as a ratio of 10 to 1.

You can quibble with the exact number (it's anecdotal), but the direction is consistent across studies. A large-scale field study tracking 78 professional developers across 3,148 working hours found they spend roughly 58% of their time on program comprehension alone. New developer onboarding averages six weeks — most of which is spent understanding existing systems, not producing new ones.

Addy Osmani named this asymmetry perfectly. In a March 2026 piece, he described comprehension debt:

"When a developer on your team writes code, the human review process has always been a bottleneck — but a productive and educational one. Reading their PR forces comprehension. AI-generated code breaks that feedback loop. The volume is too high."

The output looks clean, passes linting, follows conventions — precisely the signals that historically triggered merge confidence. But comprehension debt is distinct from technical debt because it accumulates invisibly — your velocity metrics, your DORA scores, your PR counts all look fine while your team's actual understanding of the codebase quietly erodes.

So here's the math: AI reduced the cost of writing abstractions to near zero. The cost of not having them — in human reading time, onboarding friction, and comprehension debt — hasn't changed at all. The break-even point for "is this interface worth it?" just shifted massively in favor of "yes."

The Data Backs It Up

This isn't theoretical. We have data on what happens when AI generates code without good abstractions.

GitClear analyzed 211 million changed lines of code between 2020 and 2024. Their findings: code churn — lines reverted or updated within two weeks — doubled compared to the pre-AI baseline. Copy-pasted code blocks rose from 8.3% to 12.3%. And refactoring-associated changes dropped from 25% to under 10%.

AI-generated code, as they put it, "resembles an itinerant contributor, prone to violate the DRY-ness of the repos visited."

The METR study (2025) found something even more striking. Experienced open-source developers predicted AI would make them 24% faster. They perceived being 20% faster while using it. They were actually 19% slower. The perception gap is the story — you feel productive while generating code that creates more work downstream.

And then there's a study from Anthropic (yes, the company that makes Claude — full disclosure). They observed 52 software engineers learning a new library. The AI-assisted group completed tasks at the same speed, but scored 17% lower on comprehension quizzes afterward — 50% versus 67%. The biggest declines were in debugging ability. You can ship code you don't understand. You can't debug code you don't understand.

Kent Beck put it bluntly: "The value of 90% of my skills just dropped to $0. The leverage for the remaining 10% went up 1000x." What that remaining 10% is, he leaves deliberately open — but it's hard to read that and not think about system design.

The Contrarian Case (And Why It Actually Agrees)

I'd be dishonest if I didn't address the people who argue against abstraction. And some of them are very smart.

Casey Muratori's "Clean Code, Horrible Performance" demonstrated that polymorphism and virtual dispatch can make code 10 to 15 times slower than straightforward procedural alternatives.

His benchmark is real. If you're writing a game engine or a high-frequency trading system, abstract interfaces on your hot path will cost you.

Dan Abramov wrote "Goodbye, Clean Code" after watching a premature abstraction make his codebase harder to modify:

"My code traded the ability to change requirements for reduced duplication, and it was not a good trade."

Sandi Metz put it more sharply: "Duplication is far cheaper than the wrong abstraction."

And Rich Hickey, in his talk "Simple Made Easy", draws the critical distinction: simple (not intertwined) is not the same as easy (familiar). Wrong abstractions complect — they braid concerns together rather than separating them.

Here's the thing: none of these are arguments against abstraction. They're arguments against bad abstraction.

Muratori's performance argument applies to hot paths in performance-critical systems — not to your REST API's service layer. Abramov and Metz argue against premature abstraction — pulling patterns out before you understand the domain. And Hickey's entire talk is a case for the right abstractions, the ones that genuinely decompose rather than complect.

The irony is that in an AI-assisted world, these arguments are easier to address. You can generate the explicit, unabstracted version first. Let it stabilize. Watch the patterns emerge. Then extract the abstraction — with AI handling the mechanical refactoring. The cost of the "duplicate first, abstract later" approach just dropped to near zero.

What This Means for You

If you're writing code with AI tools — and at this point, most of us are — the temptation is to let the AI produce whatever it produces and move on. It works. It passes the tests. Ship it.

But "it works" is table stakes. The harder question is: can the next person who opens this code understand it in under five minutes? Can you understand it in six months?

Interfaces aren't about making code prettier or satisfying some abstract (pun intended) design principle. They're compression algorithms for human cognition. They let your brain operate at the semantic level instead of the syntactic level. And now that AI has eliminated the only real cost of creating them — the boilerplate — there's no economic argument left for skipping them.

The rules haven't changed. The excuse has just expired.

References

Academic Papers

• Duran, R., Zavgorodniaia, A., & Sorva, J. (2022). "Cognitive Load Theory in Computing Education Research: A Review." ACM Transactions on Computing Education, 22(4), Article 40.

• Parnas, D.L. (1972). "On the Criteria To Be Used in Decomposing Systems into Modules." Communications of the ACM, 15(12), 1053–1058.

• Peitek, N., Apel, S., Parnin, C., Brechmann, A., & Siegmund, J. (2021). "Program Comprehension and Code Complexity Metrics: An fMRI Study." ICSE 2021. ACM SIGSOFT Distinguished Paper Award.

• Peng, S., Kalliamvakou, E., Cihon, P., & Demirer, M. (2023). "The Impact of AI on Developer Productivity: Evidence from GitHub Copilot." arXiv:2302.06590.

• Shen, J.H. & Tamkin, A. (2026). "How AI Impacts Skill Formation." arXiv:2601.20245.

• Xia, X., Bao, L., Lo, D., Xing, Z., Hassan, A.E., & Li, S. (2018). "Measuring Program Comprehension: A Large-Scale Field Study with Professionals." IEEE Transactions on Software Engineering, 44(10), 951–976.

• METR. (2025). "Measuring the Impact of Early 2025 AI on Experienced Open Source Developer Productivity." metr.org.

Talks and Blog Posts

• Hickey, R. (2011). "Simple Made Easy." Strange Loop Conference.

• Beck, K. (2023). "90% of My Skills Are Now Worth $0." Tidy First? Substack.

• Osmani, A. (2026). "Comprehension Debt: The Hidden Cost of AI-Generated Code." addyosmani.com.

• Muratori, C. (2023). "Clean Code, Horrible Performance." Computer Enhance.

• Abramov, D. (2020). "Goodbye, Clean Code." overreacted.io.

• Metz, S. (2016). "The Wrong Abstraction." sandimetz.com.

• GitClear. (2025). "AI Assistant Code Quality in 2025." gitclear.com.

An API fails in production. You restart the service, errors go away, and it feels resolved. Until it happens again. And again. What's happening here is simple: you're treating symptoms, not the underlying cause.

The 5 Whys technique is a straightforward way to deal with this. It comes from the Toyota Production System and was designed to help teams dig deeper into problems instead of settling for quick fixes.

The idea is simple. Ask "why" repeatedly until you reach the real cause.

But in practice, this is where things go wrong.

Teams often:

• Stop too early

• Assume answers without checking data

• Focus on people instead of systems

• Treat "five" as a rule instead of a guideline

So even though the process looks structured, the outcome is still shallow.

In this article, we'll focus on how to actually use the 5 Whys in real situations. Not just the theory, but what it looks like when you apply it to an engineering problem.

Here's What We'll Cover:

• What is the 5 Whys Technique?

• Origins of the 5 Whys Method

• How to Conduct an Effective 5 Whys Analysis

• Real-World Example: Applying 5 Whys in an Engineering Scenario

• When to Use (and When Not to Use) 5 Whys

• Benefits of the 5 Whys Technique

• Common Pitfalls and Limitations

• Tips for Using 5 Whys Effectively

• Summary

What is the 5 Whys Technique?

The 5 Whys technique is a way to break down a problem by repeatedly asking why it happened, with the goal of reaching a cause that actually explains the issue and can be addressed.

At its core, it's not about the number five. The name can be misleading. What matters is the process of following a chain of cause and effect until the explanation stops being superficial and starts becoming useful.

Each answer you uncover should move you one level deeper. You start with what went wrong, then explore what led to it, and continue until you reach something that is both believable and actionable. In most real situations, that final answer is not a single event but a gap in a system, a missing check, or an assumption that was never validated.

The technique became widely known through the Toyota Production System, where it was used to improve processes by focusing on causes rather than quick fixes.

That context is important because it highlights the original intent. The goal was not just to explain problems, but to prevent them from happening again.

A simple example makes this clearer. Imagine a mobile app suddenly starts crashing after a release. Asking "Why?" might look like this:

1. Why is the app crashing? → Because a null value is being accessed in the code.

2. Why is there a null value? → Because the API response is missing a required field

3. Why is the field missing? → Because a recent backend change made the field optional.

4. Why was this change not handled in the app? → Because the app assumes the field is always present.

5. Why was this assumption not caught earlier? → Because there are no contract tests validating API responses.

At this point, the issue is no longer just "fix the null check". The deeper problem is the lack of validation between systems, which allows breaking changes to slip through.

A useful way to think about the 5 Whys is that it forces you to stay with the problem a little longer than you normally would. Most of the time, the first explanation feels sufficient, so it's easy to stop there. This method pushes you to go one step further, and then another, until the explanation holds up under scrutiny.

At the same time, it's not a rigid formula. You might reach a solid root cause in three steps, or it might take more than five. The quality of the reasoning matters more than the count.

Origins of the 5 Whys Method

The 5 Whys method comes from the Toyota Production System, a manufacturing approach focused on continuous improvement and problem solving at the source.

It's often associated with Sakichi Toyoda, whose philosophy was simple: don’t just fix a problem. Understand why it happened so it doesn't happen again.

Inside Toyota, this wasn't treated as a formal tool or checklist. It was part of the day-to-day way of working. When something went wrong on the production line, the goal wasn't to get things running quickly and move on. The goal was to stop, investigate, and make sure the same issue wouldn't repeat.

That mindset is important to understand. The 5 Whys was never meant to be a rigid exercise where you ask five questions and stop. It was a way to encourage deeper thinking and accountability in processes.

Another key idea in the Toyota system is that problems are usually caused by processes, not people. Instead of asking "who made the mistake", the focus is on "what allowed this mistake to happen". The 5 Whys fits naturally into this approach because it pushes you toward system level causes rather than individual blame.

Over time, the method spread beyond manufacturing and is now used in software engineering, product teams, operations, and many other fields. The context has changed, but the core idea remains the same: if you don't understand the cause, you're likely to see the same problem again.

This origin story is useful not just as background, but as a reminder of intent. The value of the 5 Whys doesn't come from the questions themselves. It comes from the discipline of not settling for the first answer.

How to Conduct an Effective 5 Whys Analysis

A 5 Whys analysis works best when it is treated as a structured way of thinking, not a checklist to rush through. The quality of the outcome depends less on how many times you ask "why" and more on how carefully you reason through each step.

It helps to approach it in stages, each with a clear purpose.

Step 1: Define the Problem Clearly

Start with a problem statement that is specific and observable. Avoid vague descriptions like "the system is slow" or "things are failing". Instead, describe what actually happened in a way that can be verified.

For example, "API response time exceeded 5 seconds for 30 percent of requests between 2 PM and 3 PM" is much more useful than "API is slow".

A clear problem statement keeps the analysis grounded. If the starting point is fuzzy, the entire chain of reasoning will drift.

Step 2: Ask "Why" Iteratively

Once the problem is defined, begin asking why it happened. Each answer should directly address the question before it and naturally lead to the next one.

The key here is continuity. Every step should feel like a logical extension of the previous one. If you find yourself jumping topics or introducing unrelated explanations, it's a sign that the chain is breaking.

Keep going until the answers stop being immediate symptoms and start pointing toward underlying conditions or decisions.

Also, don't force the process to stop at five. Some problems may need fewer steps, while others may need more. What matters is reaching a point where the explanation is meaningful and actionable.

Step 3: Validate Each Answer with Evidence

This is where many analyses go wrong. It's easy to come up with plausible answers, but plausibility is not enough.

Each "why" should be backed by some form of evidence. This could be logs, metrics, recent changes, or direct observation. If an answer can't be verified, treat it as a hypothesis and confirm it before moving forward.

Without validation, the entire analysis becomes a chain of assumptions. Even if the final answer sounds reasonable, it may not reflect reality.

Step 4: Identify the Root Cause

A good root cause is one that explains the sequence of events and can be acted upon to prevent the issue in the future.

In many cases, this turns out to be a gap in a process rather than a single technical failure. It could be a missing validation step, an incomplete test, or an assumption that was never challenged.

If the final answer still feels like a symptom, you probably need to go one level deeper. On the other hand, if the answer points to something you can change in your system or workflow, you are likely in the right place.

Step 5: Define Corrective Actions

The analysis is only useful if it leads to meaningful action.

Once you've identified the root cause, the next step is to define changes that prevent the problem from happening again. These should go beyond quick fixes and address the underlying issue.

For example, instead of just fixing a bug, you might introduce better testing, add monitoring, or improve review processes.

Good corrective actions share a few traits: they're specific, practical to implement, and they directly address the root cause identified in the analysis.

Real-World Example: Applying 5 Whys in an Engineering Scenario

To see how this works in practice, let’s walk through a realistic backend issue. The goal here is not just to reach an answer, but to show how each step builds on evidence and leads to something actionable.

The Problem:

Users report intermittent failures while fetching order details:

GET /api/orders/{id}
→ HTTP 500 Internal Server Error

Application logs show:

// Java 21 example (Spring Boot style logging)
logger.error("Database connection timeout while fetching order", ex);

At this point, it's tempting to conclude that the database is the problem. But that's only what we can see on the surface.

Applying the 5 Whys

1. Why did the API return a 500 error?

Because the database query timed out.

This is directly supported by the error logs, so we can treat it as a confirmed fact.

2. Why did the query time out?

Because the database connection pool was exhausted.

Metrics show that all available connections were in use during peak traffic.

3. Why was the connection pool exhausted?

Because some requests were holding database connections for too long.

Slow query logs confirm that a subset of queries had unusually high execution times.

4. Why were some queries slow?

Because a recently introduced feature added a query on a non-indexed column.

Looking at recent deployments reveals a change that introduced filtering without proper indexing.

5. Why was an unoptimized query deployed to production?

Because there is no performance validation step in the development or release process.

There are no checks in code review or CI/CD to catch inefficient database queries before deployment.

Root Cause

The issue is not the timeout itself.

It's this:

The system allows inefficient database queries to reach production without any safeguards.

What a Shallow Fix Would Look Like

If we stopped early, we might:

• Increase the database timeout

• Increase the connection pool size

These might reduce the frequency of failures, but they don't solve the underlying problem.

What a Strong Fix Looks Like

A proper 5 Whys analysis leads to changes that improve the system:

• Add appropriate indexing for frequently queried fields

• Introduce query performance checks in CI/CD pipelines

• Add monitoring and alerts for slow queries

• Include database considerations in code reviews

Why This Example Matters

The difference between a shallow fix and a real solution is depth.

The first explanation often feels sufficient, especially under pressure. But stopping there means the issue is likely to return in a different form.

The value of the 5 Whys comes from following the chain all the way to something you can change in your system.

When to Use (and When Not to Use) 5 Whys

Like any problem-solving method, the 5 Whys is useful in the right context and less effective in others. Knowing when to apply it is just as important as knowing how to use it.

If used appropriately, it can uncover meaningful insights. If used in the wrong situation, it can lead to oversimplified or misleading conclusions

When to Use 5 Whys

The 5 Whys is most useful when your goal is to understand why something happened, not just to fix it and move on.

It works well in situations where problems are recurring or not fully explained by the first answer. For example, production incidents, repeated bugs, or issues that reappear after a quick fix are strong signals that you need deeper analysis. In these cases, the technique helps uncover what is happening beneath the surface.

It's also effective during retrospectives and postmortems. When a release doesn't go as expected or a sprint runs into issues, the 5 Whys helps teams move beyond observations like "this failed" and get to "why did this fail in the first place".

In general, use it when:

• The problem is not obvious

• The issue has occurred more than once

• You want to prevent recurrence, not just resolve the current instance

When Not to Use 5 Whys

The 5 Whys has its limits, and using it in the wrong context can lead to oversimplified conclusions.

If a problem involves multiple interacting factors, a single chain of "why" questions may not capture the full picture. Complex systems often have several contributing causes, and forcing them into one linear explanation can hide important details. In such cases, the 5 Whys should be combined with other approaches.

It's also less effective when there's not enough data. If each answer is based on assumptions rather than evidence, the analysis quickly becomes unreliable. The method depends on validation at every step.

Another limitation is in time-critical situations. During an active incident, the priority is to restore the system. The deeper analysis should happen later, once things are stable.

Finally, if your goal is quantitative analysis or optimization, the 5 Whys alone isn't enough. You'll need more data-driven methods to support decision making.

A simple rule of thumb is this. If you are trying to learn from a problem, use the 5 Whys. If you are trying to fix something immediately or analyze complex data, use it carefully or alongside other techniques.

Benefits of the 5 Whys Technique

The 5 Whys technique is simple, but it offers several powerful benefits that can help you solve problems more effectively and make lasting improvements. Here are the key advantages:

Simple and Easy to Apply

One of the biggest strengths of the 5 Whys is how easy it is to start using. You don't need special tools, training, or complex frameworks. It can be applied in a quick discussion, during debugging, or as part of a formal postmortem.

This low barrier makes it accessible across teams, regardless of experience level.

Encourages Deeper Thinking

The method naturally pushes you to go beyond the first explanation. Instead of reacting to what's visible, it encourages you to question why the problem occurred in the first place.

This shift from surface-level fixes to deeper understanding often leads to better decisions.

Promotes System-Level Improvements

When used correctly, the focus moves away from individual people and toward systems. Instead of asking who made a mistake, the analysis asks what allowed the mistake to happen.

This leads to improvements in processes, safeguards, and overall system design rather than one-off fixes.

Works Well in Team Settings

Because the approach is simple, it's easy for multiple people to contribute. Different perspectives help uncover gaps that might otherwise be missed.

It also creates a shared understanding of the problem, which is valuable during retrospectives and incident reviews.

Helps Prevent Recurring Issues

Quick fixes often solve the immediate problem but don't stop it from happening again. The 5 Whys helps identify underlying causes, which makes it easier to prevent similar issues in the future.

Over time, this leads to more stable systems and fewer repeated incidents.

Common Pitfalls and Limitations

While the 5 Whys technique is useful, it’s not always perfect. There are some limitations to keep in mind, so you can use it effectively and know when it might not be enough.

Stopping Too Early

One of the most common mistakes is ending the analysis after the first or second answer. These early answers usually describe symptoms, not causes.

Stopping too soon leads to fixes that address the surface but leave the underlying issue unresolved.

Treating Assumptions as Facts

It's easy to come up with explanations that sound reasonable. But without evidence, they're just assumptions.

If each step isn't validated with logs, metrics, or observations, the entire analysis can drift away from reality.

Focusing on Individuals Instead of Systems

Answers like "someone made a mistake" don't add much value. While they may be true, they don't explain why the system allowed that mistake to have an impact.

Focusing on processes and safeguards leads to more meaningful improvements.

Oversimplifying Complex Problems

The 5 Whys follows a linear chain of reasoning, but real-world systems often have multiple contributing factors.

Relying on a single chain can hide important interactions. In such cases, the method should be combined with other approaches.

Treating It as a Rigid Formula

The name suggests asking "why" five times, but this shouldn't be taken literally. Some problems require fewer steps, while others need more.

Forcing the structure can lead to artificial or weak conclusions.

Not a Replacement for Deeper Analysis

The 5 Whys isn't designed for every type of problem. For complex system failures, performance optimization, or data-heavy investigations, additional tools and methods are often required.

It works best as a starting point or a complement to other techniques, not a complete solution on its own.

Tips for Using 5 Whys Effectively

To get the most out of the 5 Whys technique, there are a few tips that can help you use it effectively. These will guide you to ask the right questions and reach useful, actionable insights.

Start with a Clear, Specific Problem

A vague problem leads to vague answers. Spend a little extra time making sure the problem statement is precise and based on observable facts. This keeps the analysis grounded and avoids unnecessary detours.

Base Every Step on Evidence

Treat each answer as something that needs to be verified. Use logs, metrics, recent changes, or direct observations to support your reasoning. If something can't be validated, call it out as a hypothesis and confirm it before moving forward.

Keep the Chain Logical and Connected

Each "why" should naturally follow from the previous answer. If the reasoning starts to jump between unrelated ideas, pause and re-evaluate. A clean, logical chain is a strong indicator that you're on the right track.

Focus on Systems, Not Individuals

Avoid stopping at explanations that point to human error. Instead, ask what allowed that error to have an impact. This shift in thinking leads to improvements that actually reduce the chances of similar issues in the future.

Do Not Force Exactly Five Steps

The number five is a guideline, not a rule. Some problems become clear in three steps, while others need more exploration. Stop when you reach a cause that's both convincing and actionable.

Involve the Right People

If possible, do the analysis as a group. People from different parts of the system bring different perspectives, which helps uncover details that might otherwise be missed. It also creates shared ownership of both the problem and the solution.

Turn Insights into Actions

The analysis only matters if it leads to change. Make sure the final outcome includes clear, practical steps that address the root cause. Without this, even a well-done analysis has limited impact.

Summary

The 5 Whys is a simple technique, but using it well takes some discipline.

At its core, it's about resisting the urge to stop at the first explanation. By following the chain of cause and effect, you move from symptoms to something you can actually fix. In many cases, that turns out to be a gap in a process rather than a one-off failure.

When applied thoughtfully, it helps teams learn from problems instead of just reacting to them. Over time, this leads to better systems, fewer recurring issues, and more confidence in how problems are handled.

The key is to treat it as a way of thinking, not just a set of steps.

I have known for a while now that most learners today don't share my love of big thick books, and to be honest, I rarely read those books in their entirety. Those big books often had a lot more exposition about the code than was probably needed. As a book buyer I wanted to make sure that I was getting my money's worth so the thicker they were, the better. It is much more common these days for learners to consume blog based tutorials and videos.

If you're learning to code right now, you've probably experienced the frustration of these formats too. I want to share something I've been working on that might help.

Blogs and Videos

Blog-style tutorials mix code and the explanation of it in a top-to-bottom fashion. Scrolling through these web-based explanations feels familiar and one can copy and paste with ease. However, linking the explanation of the code and the code itself has always been less than ideal. Often I find myself jumping around the blog post wishing I could see the entire code example while working through the explanation. Instead, I am only able to see small parts of the code and it is challenging to see how those parts relate to other parts.

Video tutorials are very popular these days. They solve some of the problems associated with blog-style tutorials. Videos are great because you get two streams of information: the author's audible narrative and the code being written. A viewer can focus on the two streams simultaneously. However, videos have some problems too.

Viewing Videos

From the perspective of the viewer, videos are hard to search through and are not useful as a copy and paste source or a code reference. More importantly, though, they discourage the viewer from taking their time and reflecting on the material. Often, when I am viewing a video tutorial I don't pause and let concepts sink in before the video moves on. Yes, I could be more disciplined and pause and rewind more often but usually I don't.

Making videos

From the perspective of the video creator, it is clear that not all code being developed is interesting to watch. Some of it is not really worth showing the viewer. Not all video creators can keep the narrative interesting the whole time.

I know I struggle with the 'performance' aspect of making videos (you won't find me coding on Twitch anytime soon). Many times after I am done making a video, as I review it, I wish I had mentioned something that I forgot. It is hard to go back and edit the video without scrapping it and starting over.

Storyteller

I have created a new medium to guide viewers through code examples. It combines the best of books, blog posts, and videos. This new medium allows a developer to write code using a top-notch editor (Visual Studio Code) and then replay the development of that code in the browser.

The author can add comments at important points in the evolution of the code. The comments can include text, hand drawn pictures, screenshots, and audio and video recordings. This allows the author to add visualizations that we have in our heads but don't make it into the code itself. The tool is called Storyteller.

Here are a few examples of a 'playback':

• Enlarging a Picture (Python)

• Dynamic Variables and Pointers (C++)

These work best on a big screen. If you are viewing a playback on a small screen you can view it in 'blog' mode (there is button in the top right to switch from 'code' mode to 'blog' mode).

I have created groups of these guided code walk-throughs to help me teach different topics to my students. These are all free and hosted on a website I created called Playback Press. Here are some of the 'books' I have created so far:

• An Animated Introduction to Programming in C++

• An Animated Introduction to Programming with Python

• An Introduction to Web Development from Back to Front

• An Animated Introduction to Clojure

• An Animated Introduction to Elixir

• Database Design and SQL for Beginners

• Mobile App Development with Dart and Flutter

• OO Design Patterns with Java

I usually assign these as readings in my classes instead of using expensive textbooks. It is a lot easier for me to write several programs than it is to find a perfect textbook.

I also use them for in-class demos instead of writing code live. This makes code demos flow much faster and smoother. If I make an interesting mistake while preparing the code I can still highlight it with a comment. If I make an uninteresting or embarrassing mistake I can just ignore it and the students won't focus on it.

The Advantages of Code Playbacks:

• The primary focus is on the code. It is always visible and easy to search and navigate.

• Since the code is so accessible, the explanation of it tends to be short and concise.

• The narrative can include whiteboard style drawings, screenshots, or videos of running code in addition to a text explanation.

• As an author, I can review the code several times and add/edit comments each time I go through it. I don't have to give a perfect performance like I do with a video.

• Comment points highlight when the author wants the viewer to take a moment to really think about the code and reflect on it. The playback only moves forward when the viewer is ready.

• The code mentioned in a comment can be highlighted so the viewer knows exactly where they should be looking.

• The code can be downloaded at any point in the playback. Then a viewer can run it, change it, and add to it.

• The tool is a language independent editor plug-in and can be used to describe programs in any language.

• Viewers only need a web browser to go through a playback.

Recently, I've been exploring how to make playbacks even more useful for learners.

AI as an Infinitely Patient Tutor

I have extended code playbacks to include an AI tutor. One thing I've learned in my years of teaching is that students often hesitate to ask questions. They worry about looking foolish, or they don't want to slow down the class, or they simply can't articulate what's confusing them.

What if every student had access to a patient tutor who never got frustrated with repeated questions and could explain concepts in multiple ways until something clicked?

I've integrated AI directly into the playback experience. As students work through a playback, they can ask questions about anything they're seeing. This might be a specific line of code, a concept I mentioned in a comment, or how something connects to material from earlier in the playback. The AI has full context. It can see the code, it understands where the student is in the playback, and it can provide explanations tailored to that exact moment. The AI is right there with the student, looking at the same code, understanding the same context.

The AI can also generate self-grading multiple choice questions based on the code and comments in a playback. These low-stakes quizzes make the learning experience more engaging and help learners check their understanding as they go.

Let me be clear: the AI doesn't replace me as an instructor. I still create the playbacks. I still decide what concepts to cover, what order to present them, and what examples best illustrate the ideas. The AI is an extension of my teaching, not a replacement for it.

Note: The AI features are available to registered users on Playback Press. Registration is free but logging in is required to access the AI tutor. If you want to see what this feels like, try one of the playbacks linked above and ask the AI a question about what you're seeing.

Conclusion

My goal has always been to help people learn to code. Books gave us depth but demanded commitment. Blogs gave us accessibility but fragmented the code. Videos gave us narrative but took away control. Playbacks keep the code front and center while letting learners move at their own pace and reflect when they need to. Adding AI doesn't change that philosophy, it just means there's always someone available to answer questions. Together, they get closer to the experience of having an expert sit beside you and walk you through a program. That's what I've been trying to build, and I think we're getting there.