A junior nurse should not be able to access every patient record in the hospital. A contractor should not be able to read internal financial reports. An employee logged in from an unrecognized device at 2AM probably should not be editing production configuration files.

Simple role-based systems handle obvious cases well. But as applications grow and access rules become more nuanced, those systems start to crack. You end up creating more and more specific roles, like finance_viewer, finance_viewer_us_only, finance_viewer_us_only_readonly, until the roles themselves become unmanageable.

Attribute-Based Access Control (ABAC) was designed to solve exactly this problem. It shifts from "what role does this user have?" to "what do we know about this user, this resource, and this situation?" and makes access decisions based on all of those factors together.

In this guide, you'll learn how ABAC works, how it evolved from earlier access control models, how policies are structured, how to implement it in code, and when to use it.

Table of Contents

• Prerequisites

• How Access Control Has Evolved

• What is Attribute-Based Access Control?

• The Four Building Blocks of ABAC

• How an ABAC Decision is Made

• How to Write ABAC Policies

• How to Implement ABAC in Code

• ABAC vs RBAC: When to Use Which

• Real-World Use Cases

• Enterprise ABAC Considerations

• Limitations and Challenges

• Conclusion

• Glossary

Prerequisites

To get the most from this article, you should have:

• A basic understanding of web authentication (logins, sessions, tokens)

• Familiarity with how users and resources relate in applications

• Some experience reading JavaScript or pseudocode

No prior knowledge of access control theory is required.

How Access Control Has Evolved

To understand why ABAC exists, it helps to understand what came before it and why each generation fell short.

Discretionary and Mandatory Access Control

Early access control models emerged from Department of Defense applications in the 1960s and 1970s. According to NIST Special Publication 800-162, these were Discretionary Access Control (DAC) and Mandatory Access Control (MAC).

In DAC, the owner of a resource decides who can access it. Think of a file on your computer where you choose who can read or edit it. In MAC, access is governed by a central authority using labels like "Classified" or "Top Secret." The system enforces these labels, not individual owners.

Both worked for their original purposes but didn't scale well to the complexity of modern networked systems.

Identity-Based Access Control and Access Control Lists

As networks grew, identity-based access control (IBAC) became common. The most familiar implementation is the Access Control List (ACL), a list of users or groups attached to a resource, specifying what each can do.

ACLs are simple and transparent, but they create a management burden as systems grow. Every new user needs to be added to every relevant list. Every permission change means hunting through lists across multiple resources. And when someone leaves the organization, you need to find and remove them everywhere.

Failure to do this consistently leads to users accumulating privileges they should no longer have.

Role-Based Access Control

Role-Based Access Control (RBAC) was a major step forward. Instead of assigning permissions directly to users, RBAC assigns them to roles. Users are then assigned roles. A hospital might have roles like nurse, doctor, admin, and billing_staff, each with different permissions.

This made administration much more manageable. Adding a new employee means assigning them appropriate roles. Removing an employee means removing their roles. Changing what nurses can do means updating the nurse role once.

RBAC became widely adopted and is still the right choice for many applications. But it has a structural weakness: as permission requirements become more granular, you have to create more specific roles. A nurse who can only see patients on their floor, only during their shift, or only for certain record types, needs a very specific role, or a combination of roles that interacts in complicated ways.

This proliferation is called "role explosion." The roles multiply until they are as difficult to manage as the individual permissions RBAC was supposed to replace.

Attribute-Based Access Control

ABAC emerged as a response to role explosion. Instead of assigning roles that bundle fixed permissions, ABAC evaluates the actual characteristics of the user, the resource, and the context at the moment of every access request.

A nurse gets access to a patient record not because they have the nurse role, but because their job title is "Nurse Practitioner," the patient is on their assigned floor, it's currently their shift, and the record type is within their scope of care. Change any of those facts, and the access decision changes accordingly.

As NIST SP 800-162 defines it, ABAC is:

"an access control method where subject requests to perform operations on objects are granted or denied based on assigned attributes of the subject, assigned attributes of the object, environment conditions, and a set of policies that are specified in terms of those attributes and conditions."

What is Attribute-Based Access Control?

ABAC is a logical access control model where every access decision is made by evaluating a set of rules against the current values of attributes. Nothing is pre-computed or cached in role assignments. Every time a user tries to do something, the system asks: given what we know about this user, this resource, and this moment, should this be allowed?

This makes ABAC highly precise and highly dynamic. Permissions don't accumulate over time. They don't need manual cleanup when someone's role changes. The system simply evaluates the current state of attributes every time.

The model is formally described in NIST's guide to ABAC as being capable of enforcing both Discretionary Access Control and Mandatory Access Control concepts, making it more expressive than models that only support one or the other.

Companies like Axiomatics, major government agencies, and large enterprises managing cross-organizational data sharing all rely on ABAC for its ability to scale security policies across complex environments.

The Four Building Blocks of ABAC

Every ABAC system is built from four types of information. Understanding these clearly is the key to understanding how ABAC works.

1. Subject Attributes

The subject is whoever or whatever is requesting access. This is usually a user, but it can also be a service, an application, or an automated system, what NIST calls a Non-Person Entity (NPE).

Subject attributes describe who the subject is:

user.jobTitle         = "Nurse Practitioner"
user.department       = "Cardiology"
user.clearanceLevel   = "Confidential"
user.employmentStatus = "Active"
user.location         = "Floor 3"
user.shiftActive      = true

These attributes are typically sourced from an identity provider, HR system, or user directory. They're facts about the user that can be used in policies.

2. Object Attributes (Resource Attributes)

The object is whatever the subject is trying to access. This could be a file, a database record, an API endpoint, a service, or any other protected resource.

Object attributes describe what the resource is:

record.type           = "PatientMedical"
record.floor          = "Floor 3"
record.sensitivity    = "High"
record.owner          = "Dr. Williams"
record.department     = "Cardiology"

Object attributes are typically assigned when a resource is created and updated throughout its lifecycle. They're facts about the resource that determine who should be able to access it.

3. Action Attributes

The action is what the subject is trying to do to the object. Common actions include read, write, edit, delete, copy, execute, and share.

In many ABAC implementations, the action itself has attributes:

action.type           = "read"
action.bulk           = false

Policies can restrict which actions are allowed independently of the other attributes. A user might be able to read a document but not delete it, even if all their other attributes match.

4. Environment Conditions

Environment conditions are contextual factors that don't belong to either the subject or the object, but that should influence the access decision. NIST describes these as "dynamic factors, independent of subject and object, that may be used as attributes at decision time to influence an access decision."

Examples include:

environment.time           = "14:30"
environment.dayOfWeek      = "Wednesday"
environment.userLocation   = "Corporate Office"
environment.ipAddress      = "192.168.1.10"
environment.deviceStatus   = "compliant"
environment.threatLevel    = "low"

Environment conditions are what make ABAC truly dynamic. The same user, the same resource, and the same action might be allowed during business hours on a trusted device but denied at midnight from an unknown IP address.

How an ABAC Decision is Made

When a subject tries to perform an action on an object, the ABAC system runs through a specific process:

Step 1: Collect Attributes

The system gathers current attributes for the subject, object, action, and environment. This might involve querying a user directory, reading resource metadata, and checking current time and location.

Step 2: Find Applicable Policies

The system identifies which policies apply to this particular request. A request to read a patient record might have several policies that apply: one about clinical staff access, one about after-hours access, and one about record sensitivity levels.

Step 3: Evaluate Each Policy

Each applicable policy evaluates the collected attributes and returns permit or deny.

Step 4: Reconcile Conflicts

If multiple policies apply and they conflict, the system uses predefined combining rules. Common approaches are "deny overrides" (if any policy says deny, the request is denied) or "permit overrides" (if any policy says permit, the request is permitted).

Step 5: Enforce the Decision

The system grants or denies access based on the final decision.

This process happens every time an access request is made. There's no caching of role assignments or pre-computed permission tables. The decision reflects the current state of all attributes at the moment of the request.

How to Write ABAC Policies

Policies are the logic at the heart of ABAC. They're written as conditional rules that reference attributes. A well-written policy reads like a business rule, because that's exactly what it is.

Simple Boolean Policy

The most basic form evaluates whether certain attributes match:

// Policy: Only active employees can access internal resources
function canAccessInternalResource(user) {
  return user.employmentStatus === "Active";
}

What this does: Checks a single attribute, employment status, before allowing access. Any inactive, suspended, or terminated user is denied, regardless of their roles or past access history.

Multi-Attribute Policy

Real policies typically combine multiple attributes:

// Policy: A nurse can read a patient record
// if the patient is on their assigned floor
// and during their active shift

function canReadPatientRecord(user, record, environment) {
  const isNurse = user.jobTitle === "Nurse Practitioner";
  const isAssignedFloor = user.assignedFloor === record.floor;
  const isActiveDuty = user.shiftActive === true;

  return isNurse && isAssignedFloor && isActiveDuty;
}

What this does: Combines three conditions using AND logic. All three must be true for access to be granted. Change the nurse's floor assignment, and they immediately lose access to records on the previous floor, without any manual intervention.

Environment-Aware Policy

Adding environment conditions makes policies context-sensitive:

// Policy: Users can only access sensitive financial records
// during business hours from the corporate network

function canAccessSensitiveFinancialRecord(user, record, environment) {
  const isFinanceStaff = user.department === "Finance";
  const isHighSensitivity = record.sensitivity === "High";
  
  // If this is a high-sensitivity record, apply time and location controls
  if (isHighSensitivity) {
    const currentHour = new Date(environment.timestamp).getHours();
    const isBusinessHours = currentHour >= 9 && currentHour < 17;
    const isCorporateNetwork = environment.ipRange === "corporate";

    return isFinanceStaff && isBusinessHours && isCorporateNetwork;
  }

  // Lower sensitivity records only require finance department membership
  return isFinanceStaff;
}

What this does: Applies stricter controls to higher-sensitivity resources. The same user gets access to low-sensitivity records at any time, but high-sensitivity records require them to be on the corporate network during business hours. The policy logic mirrors the actual business rule: sensitive data needs more protection.

Ownership-Based Policy

ABAC can also implement discretionary ownership rules:

// Policy: A user can edit a document
// if they own it, or if they have editor permissions
// and the document isn't locked

function canEditDocument(user, document, action) {
  const isOwner = document.ownerId === user.id;
  const hasEditorPermission = user.permissions.includes("document.edit");
  const isUnlocked = document.status !== "locked";

  return (isOwner || hasEditorPermission) && isUnlocked;
}

What this does: Combines ownership (an attribute of the relationship between user and document) with explicit permissions and resource state. An editor can't edit a locked document even if they have the edit permission. An owner can edit their own documents but not locked ones.

How to Implement ABAC in Code

Let's build a simple ABAC evaluation engine that puts these pieces together.

Step 1: Define the Attribute Structure

First, define clear data structures for your attributes:

// A user (subject) requesting access
const user = {
  id: "user-123",
  name: "Sarah Chen",
  department: "Cardiology",
  jobTitle: "Nurse Practitioner",
  clearanceLevel: 2,
  assignedFloor: "Floor 3",
  shiftActive: true,
  employmentStatus: "Active"
};

// A resource (object) being accessed
const patientRecord = {
  id: "record-456",
  type: "PatientMedical",
  floor: "Floor 3",
  sensitivity: 2,
  ownerId: "doctor-789",
  department: "Cardiology"
};

// Environment conditions
const environment = {
  timestamp: new Date().toISOString(),
  ipAddress: "10.0.1.25",
  ipRange: "corporate",
  deviceCompliant: true
};

Step 2: Write Policy Functions

Write individual policies as pure functions that take attributes and return boolean values:

// policies/patientRecord.js

// Policy 1: User must be active and clinical staff
function isClinicalStaff(user) {
  const clinicalTitles = [
    "Nurse Practitioner",
    "Physician",
    "Resident",
    "Medical Assistant"
  ];
  return (
    user.employmentStatus === "Active" &&
    clinicalTitles.includes(user.jobTitle)
  );
}

// Policy 2: Record must be within the user's assigned area
function isAssignedToRecord(user, record) {
  return (
    user.department === record.department &&
    user.assignedFloor === record.floor
  );
}

// Policy 3: User must be on active shift
function isOnActiveShift(user) {
  return user.shiftActive === true;
}

// Policy 4: High-sensitivity records require compliant devices
function meetsDeviceRequirements(record, environment) {
  if (record.sensitivity >= 3) {
    return environment.deviceCompliant === true;
  }
  return true; // No device requirement for lower sensitivity
}

What this does: Each policy is a small, focused function. This makes policies easy to test individually, easy to read, and easy to reuse across different access decisions. A policy for "is this user clinical staff" can be applied to many different resource types.

Step 3: Build an Evaluation Engine

Combine your policies into a decision engine:

// abac/engine.js

function evaluateAccess(user, resource, action, environment, policies) {
  // Collect all policy results
  const results = policies.map(policy => {
    try {
      return policy(user, resource, action, environment);
    } catch (error) {
      console.error(`Policy evaluation error: ${error.message}`);
      return false; // Fail closed: deny on error
    }
  });

  // Deny-overrides: if any policy denies, access is denied
  return results.every(result => result === true);
}

// Assemble policies for reading patient records
const readPatientRecordPolicies = [
  (user) => isClinicalStaff(user),
  (user, record) => isAssignedToRecord(user, record),
  (user) => isOnActiveShift(user),
  (user, record, action, environment) => meetsDeviceRequirements(record, environment)
];

// Make an access decision
const canRead = evaluateAccess(
  user,
  patientRecord,
  "read",
  environment,
  readPatientRecordPolicies
);

console.log(`Access ${canRead ? "granted" : "denied"}`);
// → Access granted (all conditions met)

What this does: The engine loops through each policy function, passing in the relevant attributes. If all policies return true, access is granted. If any returns false, access is denied. This is called "deny-overrides combining". The try-catch ensures that if a policy throws an error, access is denied rather than granted, following the security principle of fail-closed.

Step 4: Add Attribute Collection

In a real application, attributes come from multiple sources:

// attributes/collector.js

async function collectAttributes(userId, resourceId) {
  // Collect in parallel for performance
  const [user, resource, environment] = await Promise.all([
    fetchUserAttributes(userId),      // From identity provider or HR system
    fetchResourceAttributes(resourceId), // From resource metadata store
    collectEnvironmentConditions()    // Time, IP, device status
  ]);

  return { user, resource, environment };
}

async function fetchUserAttributes(userId) {
  // This would query your user directory, LDAP, or identity provider
  const user = await userDirectory.findById(userId);
  const shift = await shiftService.getActiveShift(userId);
  
  return {
    ...user,
    shiftActive: shift !== null,
    assignedFloor: shift?.floor || null
  };
}

async function collectEnvironmentConditions() {
  return {
    timestamp: new Date().toISOString(),
    ipAddress: request.ip,
    ipRange: await networkService.classifyIP(request.ip),
    deviceCompliant: await deviceService.checkCompliance(request.deviceId)
  };
}

What this does: Attribute collection is separated from policy evaluation. This is an important design decision: it means you can test policies with any attribute values without needing real users or resources. It also means you can swap out the source of attributes (say, moving from an on-premise directory to a cloud identity provider) without changing your policies.

Step 5: Integrate with Your API

Use the evaluation engine in your API handlers:

// middleware/abac.js

function requireAccess(action, resourceType) {
  return async (req, res, next) => {
    try {
      const { user, resource, environment } = await collectAttributes(
        req.user.id,
        req.params.id
      );

      const policies = getPoliciesFor(resourceType, action);
      const allowed = evaluateAccess(user, resource, action, environment, policies);

      if (!allowed) {
        // Log the denial for audit purposes
        auditLog.record({
          userId: req.user.id,
          resourceId: req.params.id,
          action,
          decision: "denied",
          timestamp: new Date()
        });

        return res.status(403).json({ error: "Access denied" });
      }

      next();
    } catch (error) {
      // Fail closed: deny access on unexpected errors
      return res.status(403).json({ error: "Access denied" });
    }
  };
}

// Use in route definitions
app.get(
  "/patient-records/:id",
  authenticate(),                               // First verify identity
  requireAccess("read", "patientRecord"),       // Then evaluate ABAC
  patientRecordController.getById               // Then handle the request
);

What this does: The ABAC check lives in middleware that runs between authentication and the route handler. Authentication establishes who the user is. ABAC decides whether that user can do what they're trying to do. This separation keeps authorization logic out of your business logic.

ABAC vs RBAC: When to Use Which

RBAC isn't obsolete. It's genuinely the right choice for many applications. The question is which model fits your specific access requirements.

RBAC Strengths

RBAC is simple to understand, simple to implement, and simple to audit. If you can describe your access requirements as a list of roles with fixed permissions, RBAC works well. Most SaaS applications start with RBAC and it serves them fine for years.

A typical RBAC check looks like:

// Simple RBAC: does the user have the required role?
function canAccess(user, requiredRole) {
  return user.roles.includes(requiredRole);
}

It's fast, clear, and easy to debug. When something goes wrong, you check which roles the user has and which roles the resource requires.

Where RBAC Breaks Down

RBAC struggles when permissions need to depend on factors that aren't captured by a role. If you need to express "finance managers can view financial records, but only for their own region, and only during business hours," you're outside what a role alone can express cleanly.

You either need an extremely specific role (finance_manager_us_east_business_hours) that creates the role explosion problem, or you add conditional logic to your application code that effectively recreates ABAC, just in a less organized way.

RBAC vs ABAC Comparison

Combining Both Models

RBAC and ABAC work well together. A common pattern is to use RBAC for coarse-grained access control (which sections of your application can this user see?) and ABAC for fine-grained control within those sections (which specific records can they access?).

For example, a role might grant access to the patient records section of a hospital system. Within that section, ABAC policies determine which specific records a user can view or edit based on their department, assigned floor, and active shift.

Real-World Use Cases

Healthcare Records Management

Healthcare is one of the clearest examples of why ABAC matters. Patient privacy regulations require precise access control, and patient care requires that the right staff can access records quickly when they need them.

An ABAC policy in a hospital might allow a nurse to view a patient's record only when:

1. the patient is currently admitted to the nurse's assigned floor,

2. the nurse is on an active shift,

3. the access occurs from within the hospital network,

4. and the record type is within the nurse's care scope.

According to WorkOS's ABAC analysis, in emergency situations ABAC systems can automatically expand access rights. For example, an ER doctor automatically gains broader access to patient records to provide immediate care, with this access being time-bound and closely monitored.

All of these rules would require dozens of roles in an RBAC system, and those roles would still struggle to handle the emergency access scenario dynamically.

Corporate Data Access

Large enterprises typically have employees across departments, roles, locations, and clearance levels who need different views of the same underlying data. A document might be accessible to finance managers in the US region during business hours, accessible to executives globally at any time, but inaccessible to contractors entirely.

ABAC expresses all of these rules in policies. As employees change departments, go on leave, or change roles, their attributes update in the identity system and their access changes automatically, with no manual ACL updates required.

Government and Classified Information

The US federal government's adoption of ABAC is described in NIST SP 800-162, which was developed to address the Federal Identity, Credential, and Access Management (FICAM) requirements. Federal agencies deal with information shared across organizational boundaries, with varying classification levels and need-to-know requirements.

ABAC allows an analyst in one agency to access information from another agency without requiring the second agency to pre-provision an account for them. The analyst's clearance attributes, organizational affiliation, and project assignments are evaluated against the resource's classification and access rules at the time of the request.

Multi-Tenant SaaS Applications

SaaS applications that serve multiple organizations need to ensure strict data isolation between tenants while supporting complex permission structures within each tenant.

ABAC handles this naturally. A resource attribute like record.tenantId is evaluated against the user attribute user.tenantId, and no cross-tenant access is possible through policy. Within a tenant, ABAC supports as much complexity as the tenant's policies require.

Enterprise ABAC Considerations

Deploying ABAC at enterprise scale introduces several challenges that don't exist in smaller implementations.

Policy Administration

Policies need to be authored, reviewed, tested, and deployed. According to NIST SP 800-162, this requires a Policy Administration Point (PAP), an interface for creating and managing policies. Without proper tooling, policies become difficult to audit and maintain.

In practice, this means treating policies like code: version control, code review, and automated testing.

Attribute Quality and Freshness

ABAC is only as good as the attributes it evaluates. If user attributes are stale, for example, for a user who changed departments but whose directory entry hasn't been updated, the access decisions will be wrong.

NIST warns that "attributes that are not refreshed as often will ultimately be less secure than attributes that are refreshed in real time." Building reliable attribute pipelines from authoritative sources is often the hardest part of ABAC deployment.

Performance

Evaluating policies on every request has a performance cost. Each evaluation may require fetching attributes from multiple sources. To manage this, many implementations use attribute caching, but caching introduces the staleness problem described above.

The solution is to cache with appropriate TTLs (time-to-live values) based on how quickly each attribute type can change. A user's department changes rarely and can be cached for hours. A user's active shift status might change every 8 hours and needs a shorter cache. Real-time location might not be cacheable at all.

Audit Logging

Because ABAC makes decisions dynamically, auditing requires logging the attributes used in each decision, not just the decision itself. A log entry that says "access denied" is only useful if it also captures why access was denied and which attributes failed to satisfy which policies.

NIST notes that without tracking attribute values at decision time, accountability requirements can't be met.

Limitations and Challenges

ABAC is powerful, but it's not the right solution for every access control problem. It's worth being honest about its limitations before committing to an implementation.

Complexity: According to NIST SP 800-162, "an ABAC system is more complicated, and therefore more costly to implement and maintain, than simpler access control systems." The flexibility that makes ABAC powerful also makes it harder to reason about. A user asking "why can't I access this?" requires examining all the attributes that were evaluated and which conditions weren't met.

Policy Conflicts: In complex systems with many policies, conflicts between policies can occur. Two policies might individually seem correct but together produce unexpected results. Resolving these conflicts requires clear precedence rules and careful policy design.

Attribute Management Overhead: Maintaining accurate attributes across large user populations requires investment in identity infrastructure. Attributes from different systems need to be normalized, validated, and kept synchronized. As NIST describes it, organizations need an entire attribute management infrastructure, not just a policy engine.

Testing is Hard: Because access depends on the combination of potentially dozens of attributes, testing edge cases comprehensively requires thought. A policy that works correctly for typical cases might behave unexpectedly for unusual attribute combinations.

Not Always Worth the Investment: For applications with straightforward access requirements, ABAC introduces unnecessary complexity. If your needs can be expressed cleanly as a set of roles with fixed permissions, RBAC is the better choice.

Conclusion

Attribute-Based Access Control represents a genuine evolution in how applications manage authorization. Rather than maintaining ever-growing lists of roles and permissions, ABAC evaluates the actual characteristics of users, resources, and context at the moment of every request.

It solves the role explosion problem that plagues complex RBAC implementations. It enables access rules that reflect real business policies rather than technical approximations of them. It handles dynamic scenarios, emergencies, time-based restrictions, and cross-organizational access that are difficult or impossible to express with static roles.

But ABAC isn't universally better. It's more complex to build, harder to debug, and requires investment in attribute management infrastructure that simpler models don't need. Many applications are well-served by RBAC, and some use RBAC and ABAC together.

The right question isn't "should I use ABAC?" It's "are my access requirements complex enough that the investment in ABAC pays off?" If your access rules change frequently, depend on resource or environment context, or need to scale across organizational boundaries, ABAC is worth serious consideration.

Start by identifying where your current access control model is breaking down. If you're creating roles to represent every edge case, if you're writing conditional logic inside route handlers that checks specific attribute values, or if users are accumulating permissions they should no longer have, those are signals that a more expressive model would help.

ABAC is the tool for when roles aren't enough.

Glossary

ABAC (Attribute-Based Access Control): An access control method where authorization decisions are made by evaluating policies against the attributes of subjects, objects, actions, and environment conditions. Defined by NIST as the approach where "subject requests to perform operations on objects are granted or denied based on assigned attributes."

Subject: The entity requesting access to a resource. Usually a human user, but can also be a service, automated process, or device. Also called the "requestor."

Object: The resource being protected, such as a file, database record, API endpoint, service, or any system resource whose access is managed by the ABAC system.

Attribute: A characteristic of a subject, object, action, or environment expressed as a name-value pair. For example, user.department = "Finance" or record.sensitivity = "High".

Subject Attributes: Properties describing the user or service making the request, such as job title, department, clearance level, or current location.

Object Attributes: Properties describing the resource being accessed, such as its type, owner, sensitivity level, or department.

Environment Conditions: Contextual factors independent of both subject and object that influence access decisions. Examples include time of day, day of week, IP address, device compliance status, or current threat level.

Policy: A rule or set of rules that evaluates attribute values to determine whether a specific access request should be permitted or denied. ABAC policies are typically written as logical conditions.

Policy Decision Point (PDP): The component of an ABAC system that evaluates policies and attributes to compute an access decision.

Policy Enforcement Point (PEP): The component that intercepts access requests and enforces the decisions made by the PDP.

Policy Information Point (PIP): The component that retrieves attribute values needed by the PDP to make decisions.

Policy Administration Point (PAP): The component that provides an interface for creating, testing, and managing policies.

RBAC (Role-Based Access Control): An access control model that assigns permissions to roles and users to roles. Simpler than ABAC but less expressive for complex, dynamic access requirements.

Role Explosion: The proliferation of increasingly specific roles in an RBAC system as access requirements become more granular, eventually making the roles as difficult to manage as individual permissions.

DAC (Discretionary Access Control): An access control model where resource owners control who can access their resources. Common in file systems.

MAC (Mandatory Access Control): An access control model where access is governed by a central authority using classification labels, independent of resource owner preferences.

ACL (Access Control List): A list associated with a resource that specifies which users or groups have which permissions. Common in identity-based access control systems.

Non-Person Entity (NPE): A subject that is not a human user, such as an automated service, application, or network device, that can request access to resources.

Attribute Caching: Storing previously retrieved attribute values to improve performance, at the cost of potentially using stale data for access decisions.

Deny-Overrides Combining: A policy combining rule where if any applicable policy returns deny, the overall decision is deny, regardless of other policies that may return permit.

Fail-Closed: A security design principle where unexpected errors or missing information result in access being denied rather than granted, reducing the risk of unauthorized access.

Source: Definitions adapted from NIST Special Publication 800-162, Guide to Attribute Based Access Control (ABAC) Definition and Considerations, January 2014 (with updates through August 2019).

But once payments happen repeatedly rather than once, the backend becomes much more complex. Subscriptions, memberships, SaaS billing, and donation platforms all depend on repeat transactions that happen automatically over time.

Unlike one-time purchases, these systems must keep working long after the user leaves the application.

A payment failure today can become a customer support problem next week. A timing error can create duplicate charges. Small backend issues can quickly turn into lost revenue and unhappy users.

Many teams discover that recurring payment systems involve much more than calling a payment API every month. Behind the scenes, engineers deal with scheduling, retries, state management, event processing, and reliability challenges.

In this article, we'll look at seven backend challenges teams commonly face when building systems that process repeat payments and how engineering teams usually solve them. We will also look at some Python code that shows you how it looks in production systems.

What We'll Cover:

• Challenge 1: Managing Payment Schedules Reliably

• Challenge 2: Preventing Duplicate Charges

• Challenge 3: Handling Failed Payments Gracefully

• Challenge 4: Keeping System State Consistent

• Challenge 5: Processing Webhooks Correctly

• Challenge 6: Supporting Different Payment Models

• Challenge 7: Monitoring Payment Systems in Real Time

• Final Thoughts

Challenge 1: Managing Payment Schedules Reliably

The first challenge appears before a payment even starts.

When users subscribe or enroll in a recurring billing flow, the system must remember when future payments should happen. That sounds straightforward at first: you store a date and trigger a job later.

Reality becomes more difficult. Users live across different time zones. Months have different lengths. Leap years exist. Billing cycles change. Daylight Saving adjustments can create unexpected behaviour.

Suppose a customer subscribes on January 31. What happens next month? February doesn't have a 31st day. Now imagine millions of users with different payment schedules.

A simple cron job often proves insufficient.

Large systems usually separate scheduling from business logic.

A common pattern is to store billing schedules in a dedicated scheduler service rather than relying on application cron jobs. The scheduler publishes a "payment due" event when the billing date arrives, and downstream workers handle payment execution.

Teams also store the next billing date after each successful payment rather than calculating future dates on the fly. This prevents errors caused by daylight saving changes, leap years, and month-end edge cases.

Using durable job queues such as Quartz, Temporal, or cloud-native schedulers further improves reliability because missed executions can be recovered automatically.

Lets look at a Python example.

from datetime import datetime

def process_due_payments():
    subscriptions = get_due_subscriptions()

    for sub in subscriptions:
        publish_event(
            "payment_due",
            {
                "subscription_id": sub.id,
                "customer_id": sub.customer_id
            }
        )

        sub.next_billing_date = calculate_next_billing_date(
            sub.next_billing_date
        )
        save_subscription(sub)

In this example, the scheduler doesn't attempt to process the payment itself. Its only responsibility is to identify subscriptions that are due for billing and publish a payment_due event.

A separate payment service can then consume the event and execute the charge. This separation improves reliability because scheduling and payment processing can scale independently, and missed jobs can be recovered from the event queue if a service becomes unavailable.

Challenge 2: Preventing Duplicate Charges

Duplicate payment processing is one of the fastest ways to lose customer trust.

Backend systems can retry requests for many reasons: network failures happen, payment providers timeout, and service interruptions occur.

Suppose the application sends a charge request. The payment provider receives it successfully.

But before the provider returns a response, the network connection drops.

Did the charge succeed? The backend system doesn't know.

Some systems immediately retry. But if the original transaction already worked, the user may receive two charges instead of one.

This problem becomes more common in distributed systems where multiple services communicate through APIs and message queues.

Most payment platforms solve this with idempotency keys.

An idempotency key acts as a unique identifier attached to a payment request. Even if the request arrives multiple times, the payment provider knows it represents the same operation.

Instead of creating duplicate transactions, the system returns the original result. Backend engineers often treat idempotency as a mandatory design principle rather than an optional feature.

import requests

idempotency_key = f"sub_{subscription.id}_{billing_period}"

response = requests.post(
    "https://api.payment-provider.com/charge",
    json={
        "customer_id": customer.id,
        "amount": 49.00
    },
    headers={
        "Idempotency-Key": idempotency_key
    }
)

Here, every billing attempt receives a unique idempotency key based on the subscription and billing period. If the network connection fails after the provider receives the request, the backend can safely retry using the same key.

The payment provider recognizes the operation as a duplicate request and returns the original result instead of creating a second charge, protecting customers from accidental double billing.

Challenge 3: Handling Failed Payments Gracefully

Not all payment failures mean the same thing.

Cards expire. Banks decline charges. Temporary network issues happen. Users hit spending limits. Fraud systems block transactions.

A payment failing once doesn't automatically mean the customer wants to cancel a service. This creates a difficult backend decision.

Should the system retry immediately? Wait one day? Send a notification? Cancel the subscription?

Teams often build retry strategies known as dunning workflows.

These workflows determine what happens after a failed payment. Some systems attempt another charge after 24 hours. Others wait several days before trying again.

A typical dunning workflow categorises failures into temporary and permanent errors.

Temporary failures such as network issues or insufficient funds trigger automatic retries after predefined intervals, for example, after 24 hours, 3 days, and 7 days.

Permanent failures, such as expired cards, pause future retries and immediately request updated payment information from the customer.

Many teams continuously measure retry success rates and adjust retry timing based on historical recovery data.

def handle_failed_payment(payment):
    if payment.error_type == "temporary":
        schedule_retry(payment.id, hours=24)

    elif payment.error_type == "permanent":
        notify_customer(
            payment.customer_id,
            "Please update your payment method."
        )

This example shows a simple dunning workflow. Temporary failures, such as insufficient funds or transient network issues, are scheduled for automatic retry after a delay. Permanent failures, such as an expired payment method, trigger customer notifications instead.

By treating failures differently, the system can recover revenue automatically while avoiding unnecessary retries for charges that cannot succeed without user intervention.

Challenge 4: Keeping System State Consistent

Payment systems rarely exist as isolated services. A successful transaction can affect multiple systems at once.

A payment may update billing databases, activate customer access, generate invoices, send notifications, and trigger analytics pipelines.

The challenge appears when one action succeeds, but another fails.

Imagine this sequence: Payment succeeds. Invoice generation succeeds. Customer access update fails.

Now the system enters an inconsistent state. The user paid, but still can't access the service.

Distributed systems make this problem difficult because transactions across services are not always atomic.

Teams often solve this using event-driven architecture.

After a payment succeeds, the application stores both the payment result and a corresponding event in the same database transaction. A separate process then publishes the event to downstream systems.

This guarantees that customer access, invoicing, analytics, and notifications eventually receive the same source-of-truth event, reducing the risk of inconsistent states.

def complete_payment(payment):

    with database.transaction():

        save_payment(payment)

        save_outbox_event({
            "type": "payment_completed",
            "payment_id": payment.id
        })

def publish_outbox_events():
    events = get_unpublished_events()

    for event in events:
        publish_to_queue(event)
        mark_as_published(event.id)

This pattern is commonly known as the Outbox Pattern. The payment record and the corresponding event are stored within the same database transaction, ensuring that both succeed or fail together.

Even if downstream systems such as invoicing or access management are temporarily unavailable, the event remains stored and can be published later, preventing inconsistencies where a customer pays successfully but doesn't receive the service they purchased.

Challenge 5: Processing Webhooks Correctly

Modern payment systems depend heavily on webhooks.

Payment providers rarely expect applications to continuously ask whether a payment succeeded. Instead, providers send events to your backend.

For example:

• Payment completed.

• Subscription updated.

• Card expired.

• Refund issued.

• Charge failed.

Webhooks sound easy until real-world conditions appear.

Events may arrive late. Events may arrive twice. Events sometimes arrive out of order.

Imagine receiving a “subscription renewed” event before the original payment confirmation. Without careful design, systems can enter invalid states.

Teams commonly solve this with event validation, signature verification, and state reconciliation logic.

Many payment teams introduce a webhook ingestion layer that immediately stores incoming events before processing them. The event identifier becomes the idempotency key, ensuring duplicate webhooks are ignored safely.

Systems then process events asynchronously through a queue, which protects the payment provider from timeouts and allows failed events to be retried without losing data.

def process_webhook(event):

    if event_exists(event["id"]):
        return

    store_event(event)

    queue_event_for_processing(event)

This example checks whether an event has already been processed before taking any action.

By using the webhook event ID as a unique identifier, the system can safely ignore duplicates while still guaranteeing that legitimate events are processed exactly once.

Challenge 6: Supporting Different Payment Models

Not every repeat payment behaves the same way.

Some subscriptions charge a fixed amount monthly. Others depend on usage.

Membership systems may include annual plans. Donation platforms often allow users to choose flexible amounts.

Systems supporting recurring donations create an interesting example. Unlike traditional subscriptions, users may adjust contribution amounts frequently, pause payments, or donate on custom schedules. This creates additional complexity around billing rules and state management.

As products evolve, backend systems often inherit multiple payment models simultaneously.

The original architecture may have assumed one billing type. Months later, new requirements appear.

Weekly billing arrives. Trial periods arrive. Prorated upgrades arrive. Usage-based pricing arrives.

Now a simple payment service starts looking like a billing platform.

Many teams eventually redesign their systems around payment abstractions rather than hardcoded workflows.

Instead of embedding billing rules directly into application code, teams often model subscriptions, usage plans, trial periods, and recurring donations as configurable billing entities.

A billing engine evaluates these entities and generates charge requests based on predefined rules. This approach makes it easier to introduce new pricing models without rewriting core payment logic every time the business changes direction.

class BillingPlan:

    def calculate_amount(self, customer):
        raise NotImplementedError


class FixedPlan(BillingPlan):

    def calculate_amount(self, customer):
        return 20.00


class UsagePlan(BillingPlan):

    def calculate_amount(self, customer):
        return customer.active_users * 5.00

amount = customer.plan.calculate_amount(customer)
charge_customer(customer, amount)

Instead of hardcoding billing logic throughout the application, this design encapsulates pricing rules within dedicated billing plan classes. The payment system simply asks the selected plan to calculate the amount due.

As new pricing models such as annual subscriptions, free trials, or usage-based billing are introduced, developers can add new plan types without modifying the core payment workflow.

Challenge 7: Monitoring Payment Systems in Real Time

Payment failures become expensive quickly.

If a search feature fails, users might retry later. If payment processing fails, revenue disappears immediately.

This means observability becomes essential. Teams need answers to questions like:

• How many payments failed today?

• Did retries increase unexpectedly?

• Did Webhook processing slow down?

• Are certain payment methods failing more often?

Monitoring repeat payment systems requires more than server metrics. Business metrics matter too. Engineering teams often track payment conversion rates, retry success rates, churn indicators, and revenue impact.

Logs alone rarely tell the full story. Modern systems combine application monitoring, event tracing, dashboards, and alerting systems.

When payment issues happen, teams need to identify problems before customers begin filing support tickets.

Fast visibility often becomes the difference between a small incident and a major outage.

def process_payment(payment):

    try:
        charge_customer(payment)

        metrics.increment(
            "payments.success"
        )

    except PaymentError:

        metrics.increment(
            "payments.failed"
        )

        raise

if payment_success_rate < 95:
    send_alert(
        "Payment success rate below threshold"
    )

This example demonstrates how payment systems can capture operational metrics during transaction processing. Every successful and failed charge updates monitoring dashboards, allowing teams to track trends in real time.

If success rates fall below an acceptable threshold, automated alerts notify engineers immediately so they can investigate provider outages, integration issues, or infrastructure problems before significant revenue is affected.

Final Thoughts

Repeat payments look deceptively simple from the user side.

A customer subscribes once and expects everything to work automatically afterwards.

Backend systems carry the real burden. Scheduling, retries, duplicate prevention, state management, webhook processing, and observability all introduce complexity that rarely appears in early prototypes.

Teams often start with straightforward implementations and discover these problems later as scale increases.

The challenge isn't processing one payment successfully. The challenge is processing millions of payments reliably across months or years without creating customer friction.

The most effective payment systems are usually the ones users never think about.

When the backend works properly, everything feels invisible. And in infrastructure engineering, invisible is often the goal.

Hope you enjoyed this article. You can connect with me on LinkedIn.

In this article, you’ll learn how to prepare a real-world medical imaging dataset for machine learning, from initial data validation to a complete preprocessing pipeline.

We’ll use the Chest X-Ray Pneumonia dataset as our running example, but the lessons apply broadly to healthcare imaging data, including ultrasound, MRI, CT, and dermatology images.

What You'll Learn in This Article

By the end of this article, you'll know how to:

• Approach healthcare data preprocessing differently from preprocessing structured data, and recognize where standard techniques fall short

• Validate a medical imaging dataset before training to catch corrupted files, mislabels, and data leakage between train and test

• Apply six core preprocessing techniques for medical images

• Build a complete preprocessing pipeline for chest X-rays using Python with OpenCV.

What We'll Cover:

• Why Preprocessing Data Matters More in Healthcare

• The Dataset

• Before Preprocessing: Validate the Dataset

• The Six Pillars of Healthcare Imaging Preprocessing

• Pillar 1: Scaling — Making the Numbers Play Fair

• Pillar 2: Normalization — Centering the Data

• Pillar 3: Guiding the Model's Attention

• Pillar 4: Handling Missing Data

• Pillar 5: Resizing & Resampling — Fitting Everything in the Same Frame

• Pillar 6: Denoising & Artifact Handling — Cleaning the Window

• Putting it All together: A Complete Pipeline

• Try it Yourself

• Conclusion

Why Preprocessing Data Matters More in Healthcare

Imagine handing a toddler a jigsaw puzzle with missing pieces, warped edges, and pieces from three different puzzles mixed together. The toddler can't solve it, but that isn't really the toddler's fault.

The same thing happens when raw, messy data gets fed into a machine learning model. A bad prediction on a clinical image can mean a missed diagnosis.

Healthcare data tends to be messier than what most ML practitioners are used to:

• Images come from different machines, hospitals, and acquisition protocols

• Labels are inconsistent, sometimes missing, sometimes wrong

• Patient data is incomplete

• Image sizes, contrast levels, and orientations vary across sources

Poor preprocessing often leads to models that perform well on benchmark datasets but struggle to generalize to data collected from different hospitals or imaging devices.

The Dataset

This guide uses the Chest X-Ray Pneumonia dataset by Paul Mooney on Kaggle. It's a strong choice for learning preprocessing because:

• It contains around 5,800 pediatric chest X-rays

• It has two clear classes — Normal and Pneumonia

• It's already organized into train, validation, and test folders

• The images are recognizable without specialized medical training

• It exhibits almost every preprocessing challenge worth learning

The dataset is available at Kaggle: Chest X-Ray Pneumonia.

Folder Structure

After downloading, the dataset is organized like this:

chest_xray/
├── train/
│   ├── NORMAL/
│   └── PNEUMONIA/
├── val/
│   ├── NORMAL/
│   └── PNEUMONIA/
└── test/
    ├── NORMAL/
    └── PNEUMONIA/

Side-by-side comparison — Normal vs Pneumonia chest X-ray:

A quick first look at one of the images:

import os
import numpy as np
import matplotlib.pyplot as plt
from PIL import Image
import cv2

DATA_DIR = "chest_xray"
TRAIN_DIR = os.path.join(DATA_DIR, "train")

# Peek at a sample image
sample_path = os.path.join(TRAIN_DIR, "NORMAL", os.listdir(os.path.join(TRAIN_DIR, "NORMAL"))[0])
sample_image = cv2.imread(sample_path, cv2.IMREAD_GRAYSCALE)

print(f"Image shape: {sample_image.shape}")
print(f"Pixel range: {sample_image.min()} to {sample_image.max()}")
print(f"Data type: {sample_image.dtype}")

The output reveals a few useful things right away: most images are large (often around 1500×2000 pixels), pixel values fall in the 0–255 range, and image sizes vary across the dataset. Each of these observations will inform a preprocessing step.

Before Preprocessing: Validate the Dataset

Before applying any transformations, it's worth checking that the data itself is intact. This step alone catches issues that would otherwise cause training to fail silently or produce misleading results.

A simple validation function:

def validate_dataset(data_dir):
    """Scan a dataset folder and flag common data quality issues."""
    corrupted = []
    too_small = []
    nearly_black = []
    total = 0
    
    for class_name in os.listdir(data_dir):
        class_path = os.path.join(data_dir, class_name)
        if not os.path.isdir(class_path):
            continue
        for fname in os.listdir(class_path):
            fpath = os.path.join(class_path, fname)
            total += 1
            try:
                img = cv2.imread(fpath, cv2.IMREAD_GRAYSCALE)
                if img is None:
                    corrupted.append(fpath)
                    continue
                if img.shape[0] < 100 or img.shape[1] < 100:
                    too_small.append(fpath)
                if img.mean() < 5:
                    nearly_black.append(fpath)
            except Exception:
                corrupted.append(fpath)
    
    print(f"Total files scanned: {total}")
    print(f"Corrupted: {len(corrupted)}")
    print(f"Too small: {len(too_small)}")
    print(f"Nearly black: {len(nearly_black)}")
    return corrupted, too_small, nearly_black

validate_dataset(TRAIN_DIR)

Common issues this catches:

• Corrupted files — files that won't open at all

• Empty or nearly-black images — failed acquisitions or saved-as-blank files

• Wrong dimensions — thumbnails or partial downloads mixed in

• Duplicate images — the same scan appearing in both train and test (this causes data leakage)

• Mislabeled images — a normal X-ray placed in the pneumonia folder

⚠️ This step is critical, One corrupted file can crash a training loop hours into a run. One duplicate between train and test can inflate accuracy scores by several percentage points without anyone noticing.

The Six Pillars of Healthcare Imaging Preprocessing

Preprocessing for medical images can be organized around six core concerns. Two of them carry over directly from preprocessing structured data. Two need to be adapted because the mechanics change when the input is an image. And two are entirely new, they only exist once the data becomes pictures of human bodies.

Pillar 1: Scaling — Making the Numbers Play Fair

Imagine two children comparing their collections. One has 3 seashells. The other has 3,000 stickers. Asking who has more makes the answer seem obvious, but the scales are completely different. Comparing them meaningfully means putting both collections on the same measuring system.

In medical images, pixels usually range from 0 to 255 in 8-bit images, or 0 to 65,535 in some 16-bit medical DICOM images. Neural networks tend to train faster and more reliably when input values are small numbers close to zero.

The fix: Divide every pixel by its maximum possible value, bringing everything into the 0-to-1 range.

image = cv2.imread(sample_path, cv2.IMREAD_GRAYSCALE)

# Scale to [0, 1]
image_scaled = image.astype(np.float32) / 255.0

print(f"Before scaling: {image.min()} to {image.max()}")
print(f"After scaling:  {image_scaled.min():.3f} to {image_scaled.max():.3f}")

Takeaway: Pixel scaling follows the same principle as scaling any numerical feature. The values simply happen to be arranged as an image rather than a column.

Pillar 2: Normalization — Centering the Data

Imagine a teacher asks a class to rate a movie from 1 to 10. One child always gives 9s and 10s. Another spreads ratings evenly from 1 to 10. Comparing their opinions fairly requires adjusting each child's score relative to their own average.

In medical imaging even after scaling to 0–1, the overall brightness of images can vary. Some X-rays are taken with stronger exposure than others. Normalization shifts and rescales each image (or each channel) so the values are centered around zero with a standard deviation of one.

The fix: Subtract the mean, divide by the standard deviation.

# Compute mean and std from the TRAINING set only — never from validation or test
def compute_train_stats(train_dir, sample_limit=1000):
    """Compute pixel mean and std across the training set."""
    pixel_values = []
    count = 0
    for class_name in os.listdir(train_dir):
        class_path = os.path.join(train_dir, class_name)
        for fname in os.listdir(class_path):
            if count >= sample_limit:
                break
            img = cv2.imread(os.path.join(class_path, fname), cv2.IMREAD_GRAYSCALE)
            if img is not None:
                pixel_values.append(img.astype(np.float32).flatten() / 255.0)
                count += 1
    pixels = np.concatenate(pixel_values)
    return pixels.mean(), pixels.std()

train_mean, train_std = compute_train_stats(TRAIN_DIR)
image_normalized = (image_scaled - train_mean) / train_std

⚠️ Avoid this common mistake: Statistics for normalization should be computed from the training set only, never from validation or test. Including those in the calculation leaks information from the evaluation data into the model. The same statistics should then be applied to validation, test, and any new data at inference time.

Takeaway: Centering and scaling each image around the dataset's statistics is the imaging equivalent of standardizing a feature column. The pixels are now comparable across images, regardless of how bright or dim each scan happened to be.

Pillar 3: Guiding the Model's Attention

Imagine a child walking into a crowded pet store. Instead of describing every animal in sight, a parent points to the features that matter: “Look at the soft fur, the fluffy tail, and the nice small size.” The child learns where to focus their attention.

Medical image preprocessing does something similar. It highlights the regions and features most relevant to the diagnostic task.

• Region-of-interest (ROI) cropping — focus on the lung field and discard the patient's arms, machine borders, and any imprinted text

• Contrast enhancement — use techniques like CLAHE (Contrast Limited Adaptive Histogram Equalization) to make subtle lung textures more visible

• Channel selection — for images stored as RGB but containing grayscale information, convert to single-channel input to reduce noise

CLAHE applied to an X-ray:

# CLAHE enhances local contrast — useful for X-rays
clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
image_enhanced = clahe.apply(image)

# Visualize the difference
fig, axes = plt.subplots(1, 2, figsize=(12, 6))
axes[0].imshow(image, cmap='gray')
axes[0].set_title('Original')
axes[1].imshow(image_enhanced, cmap='gray')
axes[1].set_title('After CLAHE')
plt.show()

Takeaway: The goal of teaching the model what to look at hasn't changed. With structured data, the answer is in new columns. With images, the answer is in cropping, enhancement, and emphasizing the regions that carry diagnostic signal.

Pillar 4: Handling Missing Data

Imagine reading a storybook with a few damaged pages. You don’t throw away the entire book, you decide whether to skip the page, infer what might be missing, or mark it for review.

In medical imaging, missing data can mean corrupted files, missing labels, or incomplete studies rather than empty spreadsheet cells.

The same three strategies — drop, impute, flag — still apply, just with different mechanics:

# Strategy 1: Drop — remove unreadable or empty images
def is_valid_image(path):
    try:
        img = cv2.imread(path, cv2.IMREAD_GRAYSCALE)
        if img is None:
            return False
        if img.mean() < 5:           # nearly black
            return False
        if img.shape[0] < 50 or img.shape[1] < 50:  # too small
            return False
        return True
    except Exception:
        return False

# Strategy 2: Impute — rare for images, but possible (e.g., in painting to fill in missing patches). Generally avoided for diagnostic data.

# Strategy 3: Flag — track which patients are missing which modalities,
#   and let the model condition on availability. Common in multi-modal healthcare ML.

Takeaway: "Missing" in imaging data is rarely just a NaN. It can be a broken file, an unlabeled scan, an absent modality, or a black corner inside an image. The same three strategies still apply.

Pillar 5: Resizing & Resampling — Fitting Everything in the Same Frame

Imagine displaying children’s drawings on a classroom wall. If every drawing is a different size, they won’t fit neatly into the display. You resize them while preserving their proportions.

Medical images must often be resized to a common input size, but anatomical structures should retain their original shape.

The fix: Resize all images to a common shape. For medical data, how the resizing is done matters.

TARGET_SIZE = (224, 224)

# Simple resize (may distort aspect ratio)
image_resized = cv2.resize(image, TARGET_SIZE)

# Better: preserve aspect ratio with padding
def resize_with_padding(image, target_size):
    h, w = image.shape[:2]
    target_h, target_w = target_size
    scale = min(target_h / h, target_w / w)
    new_h, new_w = int(h * scale), int(w * scale)
    resized = cv2.resize(image, (new_w, new_h))
    
    pad_h = target_h - new_h
    pad_w = target_w - new_w
    top, bottom = pad_h // 2, pad_h - pad_h // 2
    left, right = pad_w // 2, pad_w - pad_w // 2
    padded = cv2.copyMakeBorder(resized, top, bottom, left, right,
                                 cv2.BORDER_CONSTANT, value=0)
    return padded

image_clean_resize = resize_with_padding(image, TARGET_SIZE)

⚠️ Why aspect ratio matters in healthcare: Squishing a chest X-ray horizontally makes the lungs look unnatural. Models trained on distorted anatomy often perform worse on real scans. Preserving aspect ratio is generally the safer choice.

Takeaway: Models need a consistent input size, but the geometry of the anatomy needs to be preserved. Resize, but resize carefully.

Pillar 6: Denoising & Artifact Handling — Cleaning the Window

Imagine looking through a window with dust and smudges on the glass. Cleaning the window makes the view clearer, but scrubbing too aggressively could scratch the glass.

Similarly, medical images often contain noise and acquisition artifacts that should be reduced carefully without removing clinically important details.

For chest X-rays, the most common issues are mild noise and burned-in text or markers. A gentle median or bilateral filter helps with the first, while cropping or masking helps with the second.

# Gentle denoising — careful not to blur away clinical detail
image_denoised = cv2.medianBlur(image, ksize=3)

# Bilateral filter preserves edges better than a median filter
image_bilateral = cv2.bilateralFilter(image, d=5, sigmaColor=50, sigmaSpace=50)

⚠️ A note of caution: Aggressive denoising can erase the features a model needs to detect a disease. For diagnostic ML, gentle filtering is generally preferred. A useful rule of thumb: if a radiologist can't distinguish the cleaned image from the original, the filtering has gone too far.

Takeaway: Imaging data carries noise that structured data doesn't have. The window can be cleaned, but never so aggressively that the view is wiped away with the smudges.

Putting it All Together: A Complete Pipeline

Here's how the six pillars combine into a single preprocessing function for chest X-ray images:

def preprocess_xray(image_path, target_size=(224, 224),
                    train_mean=0.482, train_std=0.236):
    """
    Full preprocessing pipeline for chest X-ray images.
    Applies all six pillars in order.
    """
    # Pillar 4: Validate first — skip corrupted files
    if not is_valid_image(image_path):
        return None
    
    image = cv2.imread(image_path, cv2.IMREAD_GRAYSCALE)
    
    # Pillar 5: Resize with aspect ratio preserved
    image = resize_with_padding(image, target_size)
    
    # Pillar 6: Gentle denoising
    image = cv2.medianBlur(image, 3)
    
    # Pillar 3: Enhance contrast to highlight lung texture
    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
    image = clahe.apply(image)
    
    # Pillar 1: Scale to [0, 1]
    image = image.astype(np.float32) / 255.0
    
    # Pillar 2: Normalize using training set statistics
    image = (image - train_mean) / train_std
    
    return image

Try it Yourself

Every code snippet in this article is bundled into a runnable Kaggle notebook: Chest X-Ray Preprocessing — Kaggle Notebook. Fork it, attach the dataset, and run all the cells to see each preprocessing pillar in action on real chest X-rays.

Conclusion

Here's a summary of what we've discussed in this article:

Preprocessing for structured data is about making numbers play fair so a model can see them clearly.

Preprocessing for healthcare imaging is about respecting the messy reality of how medical data is captured, stored, and labeled. Some standard techniques carry over directly. Some need to be adapted. And a few preprocessing concerns only emerge once the data becomes pictures of human bodies.

Stepping back, whether it's a child learning to organize their toy box, or a model learning to spot pneumonia in a chest X-ray, the quality of learning depends on the quality of data preparation. Get the data right.

If this was useful, you can find a related conceptual primer on preprocessing more broadly here: Data Preprocessing for Machine Learning.

The ability to scale applications instantly and ship software reliably is an important skill. Containerization is at the heart of modern development.

This hands-on, structured course is designed to take you from absolute scratch to becoming job-ready. Taught by instructor Eissa from DolfinEd, who brings over 25 years of industry experience and 21 years of teaching expertise, this course breaks down complex concepts into simple, actionable skills.

This is a complete, step-by-step practical course that covers everything you need to master Docker:

• Foundations: Understand the shift from legacy physical servers to virtual machines and containers.

• Core Skills: Master Docker files, image creation, and how to manage repositories using Docker Hub.

• Networking & Storage: Learn the gold standards for managing container networking, storage, and volumes.

• Orchestration: Move beyond basic containers by learning how to deploy multi-container applications with Docker Compose and get an introduction to Docker Swarm.

• Real-World Application: Put your skills to the test with structured quizzes, module assignments, and real-world projects that mirror professional environments.

Watch the full course now and start your journey to becoming a Docker expert (7-hour watch

One of the core features of the app is AI-assisted activity creation. Activity creation has always been a key aspect of the project, and in the earlier desktop version, this was handled through manual long-form activity submission forms.

Given the current AI landscape, it felt important to explore alternative ways to simplify and streamline activity creation using AI, while reducing the amount of manual form-filling required from users.

I started with a blank slate, letting Claude guide me on the technologies to use for the app. The app was eventually built with React Native (Expo) and Firebase, and builds on a web version that is currently in beta.

What stood out to me most during prototyping was the speed: the mobile app went from ideation and mockups to a working prototype in about a month, compared to nearly a year for the original web version.

I haven't been coding heavily in recent years, and most of my professional work today is centered around technical community management. But since I do have a technical background and prior experience working in software development, I found it surprisingly accessible to quickly build a functional app using Claude alongside its reference guides and documentation.

I do think that experience helped me reason through tradeoffs, evaluate architectural decisions, and critically analyze the generated code rather than relying on the LLM blindly.

In this article, I’ll share some of the technical design decisions I made along the way.

Table of Contents

• Prerequisites

• Which Model to Choose

• Choosing For Geography and Cost

• Choosing the Programming Framework and Backend Architecture

• Machine Translation and Multilingualism

• “Create with AI” with Humans in the Loop

• Optimizing for Low Bandwidth

• Producing a Demo Video

• Summary

Prerequisites

The key technical decisions I discuss here are reflections that come from my hands-on experimentation. They're intended for others working at the intersection of education and technology, especially developers, community practitioners, or technically curious people looking to prototype and build quickly using AI tools.

You'll need to have some basic familiarity with the React Native framework, how databases and Firebase work, as well as how to use Claude tools, command-line tools, and API integrations.

It also helps to be comfortable making decisions along the way around tradeoffs, such as choosing one infrastructure over another based on cost, geography, multilingual support, scalability, or ease of use.

Which Model to Choose

When it comes to choosing the model to build the app itself, it was a straightforward choice. I picked Opus 4.7 for its advanced capabilities because I needed the model to help architect the app from scratch.

But when it came to choosing the model inside the app, the decision required more consideration.

Before diving into the reasons for picking a model, let’s first understand the context. Some of the features in the app include lesson plan creation and structuring with AI, machine translation of the content into 10 languages, a facilitation mode that guides educators through AI-generated tips for each activity step, educator profiles, and more.

If we break these features down, the model needs to support a few key capabilities: structured JSON generation that follows strict schemas, pedagogical reasoning for activity design, multilingual content generation, and the ability to infer constraints such as time, materials, and age-appropriateness. It also needs to reliably map user inputs into predefined activity categories while maintaining consistency in output structure.

The activity generation workflow is the key AI feature in the app. Since it's an asynchronous, one-shot generation feature, I picked Sonnet among the available Claude models because of the quality and non-generic educational content it was able to generate.

Choosing For Geography and Cost

Latency and network reliability were also important considerations. The app is designed to support educators working in underserved contexts and slower network environments. Although Claude’s Haiku model would have offered lower latency, it might not be as reliable on slower networks compared to other models.

At the same time, I plan to keep the app free and open source, and I'm not currently planning to market it aggressively. Using Opus for end-user generation would therefore have been expensive, even though it may have produced richer outputs.

For a structured generation task like this, Sonnet felt like the right balance between quality, cost, and response time. Longer generation times with Opus could have negatively impacted user experience.

When it comes to configuring maxTokens in the API setup, I also made decisions keeping cost and generation length in mind.

A typical activity generated for the platform should ideally not exceed roughly 1,500–2,000 words, which translates to around 2,500 output tokens and approximately 30–45 seconds of generation time.

Based on this, I kept the maxTokens value around that range to help control token costs while still allowing enough space for meaningful structured educational content generation.

/**
 * Claude AI configuration.
 *
 * NOTE: For production, move the API key to a server-side proxy to avoid
 * exposing it in the client bundle. The `baseUrl` can be swapped to your
 * own backend endpoint that forwards requests to Anthropic.
 */
export const aiConfig = {
  apiKey: process.env.EXPO_PUBLIC_CLAUDE_API_KEY ?? '',
  model: 'claude-sonnet-4-6',
  maxTokens: 2500,
  baseUrl: 'https://api.anthropic.com/v1/messages',
  anthropicVersion: '2023-06-01',
};

Choosing the Programming Framework and Backend Architecture

I wanted to build an app using a framework that could work seamlessly on both Android and iOS devices. React Native seemed like an obvious choice here, both because it directly fit this requirement and because of its simplicity, ease of use, and overall popularity in the ecosystem.

For the database and backend, I wanted to pick a system that felt credible from both a data privacy and security perspective.

I had a slightly unexpected moment during development while discussing architecture choices with Claude Code. It suggested commonly used developer platforms, such as Supabase. At first, this felt like a reasonable default choice.

But the key here was to not just go with what's commonly suggested, and instead do a quick but thorough check on how reliably these services are accessible in the target user regions. While looking deeper, I came across reports that Supabase access had been restricted in India, likely related to cybersecurity concerns.

That immediately changed my decision. Even though Claude had initially scaffolded the backend setup assuming Supabase, I later switched the architecture to Firebase by creating a project directly in the Firebase Console.

That was one of those small but important reminders that it's not enough to accept AI suggestions at face value. It's useful to actively check for the latest context, especially when it comes to infrastructure and platform availability.

The Firebase setup itself looked fairly straightforward:

• Create a project at Firebase Console

• Enable Authentication (Email/Password)

• Create a Firestore database

• Enable Storage

• Add a Web app and copy the config values

Another pattern I noticed was that AI is very quick to suggest interesting or “modern” infrastructure choices along the way: for example, for video uploads or media handling.

But in practice, thoughtful tradeoff decisions matter much more. Especially at an early stage, when I'm still validating the app idea with a small group of educators, I don't actually need a full-scale video infrastructure. This keeps the system lightweight, reduces implementation complexity, and helps avoid overengineering before the product direction and user needs are fully validated.

The prompt I used reflected this thinking:

I am in the early validation stage for this app, focusing on feedback from a small group of educators. Therefore, we do not require a scalable and robust video infrastructure yet. Let’s design for easier alternatives, such as users uploading their videos to YouTube and simply copying the URL into a field for embedding on the activity page.

Machine Translation and Multilingualism

Given that the primary audience of the earlier version of the app was multilingual, with the platform targeting users from different Indian language communities, it was really difficult as a small project to get translation coverage for content across all languages. But with AI, machine translation is possible at least for popular languages for which training datasets are available.

For the prototyping phase, I'm providing 5 of the world’s most popular languages and 5 popular Indian languages in the language selection. At least for these languages, the machine translation quality is pretty good and AI is reasonably reliable.

Without this, it would have been a cumbersome maintenance effort in the early stages of the app, both to keep translations updated and to recruit contributors to translate content manually.

There are two translation layers in the project: a static layer for interface messages kept in a src/i18n folder, and a dynamic layer for activity content.

For the dynamic part, AI generates translations for activity content using the Google Translate API. This is the same public web endpoint that the Google Translate web widget uses. It's free and no API key is needed.

But the API is unofficial and rate limits aren't guaranteed. For production use, we'll eventually switch to something more commercial and reliable such as the Cloud Translation API.

“Create with AI” with Humans in the Loop

The core idea behind the app is to help educators document and share their creative projects. So making documentation easier through AI while still keeping educators in the loop to maintain ownership over the final published content felt like an essential design choice.

Initially, I experimented with using Claude as a conversational chat partner for activity creation. The idea was that the AI would guide educators through a back-and-forth interaction and gradually build the activity plan through follow-up questions.

But during prototyping, I realized that this often introduced too much friction into the experience. It started to feel like users were being asked too many questions, and the final outputs frequently deviated from the intended structure or became inconsistent across activities.

To make the experience as quick and lightweight as possible, the app now primarily works from a single input. Users can briefly describe their activity idea in natural language and optionally upload media files, after which the AI generates a complete structured activity plan.

Instead of relying on open-ended conversational outputs, the app uses prompts with specific guidelines and schema requirements. The generated output is strictly valid JSON following a predefined structure (for example: 3-6 activity steps, 4-5 facilitation steps depending on complexity, automatic selection of a featured image based on visual relevance, and so on). This allows the generated content to be directly consumed by the app without requiring an additional parsing or mapping layer.

If a user uploads multiple photos, the AI also identifies which images belong to which activity steps. The experience works somewhat similarly to Facebook’s “Create your listing with Meta AI” feature. Users can upload different types of media files, after which the AI generates titles, materials, objectives, activity steps, and facilitation tips.

Importantly, everything remains editable before publishing, so educators can review, refine, and personalize the final content before sharing it with the community.

Return ONLY valid JSON (no markdown, no backticks) matching this exact schema:
{
  "title": "string (catchy, max 60 chars)",
  "description": "string (2-3 sentences, educator-facing)",
  "duration_minutes": number,
  "min_age": number,
  "max_age": number or null,
  "category": one of "Art" | "Science" | "Coding" | "Circuits" | "Engineering" | "Storytelling" | "Drama" | "Film" | "Music" | "Nature",
  "materials": [{ "name": "string", "buy_hint": "string (where to find it, e.g. craft store, hardware store, recycled)" }],
  "objectives": ["string (learning objective)"],
  "steps": [{
    "number": 1,
    "title": "string",
    "description": "string (2-3 sentences, detailed instructions for the educator)",
    "duration_minutes": number,
    "tip": "string (practical facilitation tip for educators running this step for the first time)",
    "assignedPhotoIndex": number or null
  }],
  "featured_image_index": number or null,
  "tips": ["string (general facilitation tip)"]
}

Optimizing for Low Bandwidth

Keeping in mind that the app is intended for users on low-bandwidth networks during the initial development phase, I made sure to provide these constraints to Claude and ensure that the prototype included the bare minimum needed to support users on slower connections.

The app loads 10 activities at a time, and uses the Expo module expo-image-manipulator for lightweight image processing tasks such as resizing photos to 1200 px and re-encoding them as JPEGs before upload. As a result, a typical 3–5 MB image can be reduced to ~200 KB.

The AI calls are also kept text-only. While images are uploaded and stored in Firebase, they're never sent to the model itself, which helps keep requests lightweight and responsive even on slower internet connections.

Producing a Demo Video

Finally, this was probably the most fun part of the process. Before my first demo meeting with an educator, I managed to generate a ~1 minute demo video out of a 4 minute screen recording. I used Claude to identify and cut the most relevant segments, and the ffmpeg command line tool to convert the final output into the appropriate format.

After trying out numerous AI video generation tools that would exhaust my tokens pretty quickly, I eventually found myself coming back to Claude for this workflow, and it ended up working surprisingly well. 🙂

Summary

A little over a year ago, I had started implementing a similar version of this app, but never reached a functional prototype. The tooling was still evolving, and I often found myself stuck in loops of agentic errors, spending more time debugging the AI workflow itself than actually building the product. With the recent advancements in AI-assisted development tools, it has genuinely felt empowering to shape and prototype ideas much more quickly.

At the same time, one of the biggest lessons from this experience was that you can't blindly build applications using AI tools. You can't simply ask an agent to do all the work and make decisions while you go on a hike – though perhaps you can do the dishes between prompts.

Each step still needs careful evaluation. The reasoning, suggestions, and discussions generated by the agent need to be read, understood, and refined through follow-up prompts and human input.

A large part of the work involves making thoughtful decisions along the way: what model to choose and why, what tradeoffs matter most for your use case (cost, geography, latency, reasoning capability, multilingual support), what infrastructure choices make sense for hosting and scalability, what API integrations are appropriate, and what decisions should be optimized for the early stages of the app versus long-term growth.

Similarly, design decisions should be grounded in the actual needs and contexts of users rather than simply following what AI tools suggest by default.

That's ultimately what I have tried to document through this article: not just how the educational app was built, but also the reasoning and tradeoffs behind the technical and design decisions made throughout the process.

Hopefully, these reflections are useful to others experimenting with AI-assisted development, especially in educational or community-centered contexts.

And if you have ideas for evolving the app further, feel free to contribute or comment on GitHub :)

Resources

• Checkout the source code repository

• Watch demo of the final workflow

Within a week, the bug reports started coming in.

Screens freezing, API calls failing silently, Users losing form data they'd spent ten minutes filling out, one user reported the app just... stopped responding after they walked through a tunnel on the subway. I had never tested that. Why would I? It worked fine on my machine.

That experience taught me something I wish someone had told me earlier: there's a real gap between an app that works and an app that is production-ready.

I've now shipped multiple Flutter apps, and I've hit almost every wall this article covers — network failures, memory leaks, state management that made sense at first and became a nightmare at scale, and performance that felt fine in development and janked badly on a user's old device.

This article is everything I've learned from those experiences. Not theory, but actual patterns that came from actual problems.

Table of Contents

• Why "It Works on My Machine" is Dangerous in Flutter

• Development vs Production: What Actually Changes

• Network Reliability and Defensive Request Handling

• Retry Logic and the Production Request Lifecycle

• Offline Support and Local Persistence

• State Management at Scale

• Widget Rebuilds and Rendering Performance

• Async Pitfalls and the Disposed Widget Problem

• Memory Leaks and Lifecycle Management

• Observability and Crash Reporting

• Testing Production Flutter Apps

• Architecture and Long-Term Maintainability

• End-to-End Example: a Production-Grade Profile Feature

• Final Thoughts

Why "It Works on My Machine" is Dangerous in Flutter

Here's what your development environment looks like: fast internet, a powerful machine or emulator, a clean app state on every hot reload, APIs that respond in milliseconds, and you, a careful developer who deliberately follows the happy path.

Here's what your users look like: spotty mobile data, old mid-range devices, six other apps running in the background, and zero patience for a screen that stops loading without explanation.

That gap is where production bugs live.

The tricky part is that Flutter makes development feel so smooth that it's easy to mistake "works on my machine" for "ready for users."

I've made that mistake. Most Flutter developers I know have made it too. The app looks polished. The animations are butter. You demo it to a colleague, and everything goes perfectly. Then someone tries to use it while commuting on patchy mobile data, and the whole thing falls apart.

Production-ready Flutter engineering starts with accepting one uncomfortable truth: things will go wrong. Networks will fail. Devices will run low on memory. Users will background your app at the worst possible moment. The question isn't whether these things happen, but rather whether your app handles them gracefully when they do.

Development vs Production: What Actually Changes

I want to be specific here because "production is different" is easy to say and hard to internalize until you've been burned by it.

In development, a failed API call is something you notice immediately in your terminal, fix in a few minutes, and move on from. In production, that same failed API call happens to a user who sees a blank screen, has no idea why, waits a few seconds, and then either retries or uninstalls. You find out three days later when someone leaves a one-star review.

In development, a widget that rebuilds unnecessarily costs a few milliseconds you never feel. In production, on an older or lower-powered device with several apps running in the background, that same unnecessary rebuild is the thing that pushes a frame over the 16ms budget and creates a stutter the user notices.

In development, a memory leak that adds 5MB of usage over ten minutes is invisible. I once had a leak in a chat feature, an undisposed stream subscription that was completely undetectable during testing. In production, after an hour of use on a low-memory device, the OS started killing the app mid-session. Users thought it was crashing randomly. It took me an embarrassingly long time to track down.

The pattern is always the same: problems that are invisible at development scale become significant at production scale, and problems that are minor on development hardware become severe on the hardware your actual users own.

Network Reliability and Defensive Request Handling

If I had to pick one category of bug that has bitten me the most across multiple apps, it would be this one. Mobile networks are genuinely unreliable, and Flutter apps are often written as though they're not.

The most common networking pattern I see (and wrote myself for longer than I'd like to admit) looks like this:

final response = await dio.get('/user');

setState(() {
  user = response.data;
});

This works perfectly in development. But it has four ways to fail in production:

1. The request fails due to a network error, and the exception propagates unhandled

2. The user navigates away before the response arrives and setState is called on a disposed widget

3. The API returns unexpected data, and the cast throws at runtime

4. The request hangs indefinitely, and the user stares at a spinner forever

I've hit all four. Here's a version that handles them:

Future<void> loadUser(String userId) async {
  setState(() {
    isLoading = true;
    error = null;
  });

  try {
    final response = await dio.get('/user/$userId');

    // mounted checks whether this widget is still in the widget tree.
    // If the user navigated away while the request was running,
    // mounted is false. Calling setState on a disposed widget throws
    // an error — this one line prevents that entire class of crash.
    if (!mounted) return;

    setState(() {
      user = User.fromJson(response.data as Map<String, dynamic>);
      isLoading = false;
    });
  } on DioException catch (e) {
    if (!mounted) return;

    setState(() {
      // Give the user a message that is actually useful.
      // "Something went wrong" is not helpful. Knowing whether
      // they have no internet vs the server failed lets them
      // decide whether to move or wait.
      error = e.type == DioExceptionType.connectionError
          ? 'No internet connection. Please try again.'
          : 'Failed to load profile. Please try again.';
      isLoading = false;
    });
  }
}

The Three States Every Screen Needs

I used to design screens for the success case and treat loading and error as afterthoughts. That was a mistake. Every screen that fetches remote data needs all three:

@override
Widget build(BuildContext context) {
  // Loading: never leave users staring at a blank screen.
  // A spinner tells them something is happening.
  if (isLoading) {
    return const Center(child: CircularProgressIndicator());
  }

  // Error: show what went wrong and how to recover.
  // A dead end with no retry button is one of the most
  // frustrating things a user can experience.
  if (error != null) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Text(error!, style: const TextStyle(color: Colors.red)),
          const SizedBox(height: 16),
          ElevatedButton(
            onPressed: () => loadUser(widget.userId),
            child: const Text('Try again'),
          ),
        ],
      ),
    );
  }

  // Success: show the data.
  return UserProfileView(user: user!);
}

The error state with a retry button isn't a nice-to-have. It's the difference between a user who recovers from a network hiccup and a user who thinks your app is broken.

Retry Logic and the Production Request Lifecycle

Mobile networks fail all the time temporarily. A user walks past a dead zone, enters an elevator, or switches from WiFi to mobile data mid-request. The request fails but if retried two seconds later, it would succeed.

Without retry logic, every temporary network failure is a permanent failure from the user's perspective. That's a bad trade.

Future<T> withRetry<T>(
  Future<T> Function() request, {
  int maxAttempts = 3,
  Duration delay = const Duration(seconds: 1),
}) async {
  for (int i = 0; i < maxAttempts; i++) {
    try {
      return await request();
    } catch (e) {
      // On the final attempt, stop retrying and let the
      // error propagate to the caller.
      if (i == maxAttempts - 1) rethrow;

      // Wait before trying again. This gives temporary network
      // issues time to resolve and avoids hammering a server
      // that might already be struggling.
      await Future.delayed(delay);
    }
  }

  throw Exception('Retry failed');
}

Usage is straightforward:

final user = await withRetry(
  () => dio.get('/user/$userId'),
  maxAttempts: 3,
  delay: const Duration(seconds: 2),
);

For production apps with heavier traffic, look at dio_smart_retry. This implements exponential backoff, and the delay doubles between each retry, which is much more considerate of server load during actual outages.

Offline Support and Local Persistence

I learned to take offline support seriously after an embarrassing support ticket. A user had filled out a long onboarding form (15 fields), which took them several minutes, and hit submit on a spotty connection. The request failed. The form cleared. All their data was gone. They were furious, and honestly, they had every right to be.

The goal of offline support is not to replicate every feature without internet. It's to make sure users don't lose progress and don't hit dead ends.

Caching Remote Data

The strategy here is simple: every time a network request succeeds, save the result locally. Then, if the next request fails, serve what you saved last time instead of showing an error screen.

class UserRepository {
  final Dio _dio;
  final Box _cache; // Hive box

  UserRepository(this._dio, this._cache);

  Future<User> getUser(String userId) async {
    try {
      final response = await _dio.get('/user/$userId');
      final user = User.fromJson(response.data as Map<String, dynamic>);

      // Save fresh data to the cache every time a request succeeds.
      // This means the next request can fall back to this
      // if the network is unavailable.
      await _cache.put('user_$userId', user.toJson());

      return user;
    } catch (e) {
      // Network failed. See if we have something cached.
      final cached = _cache.get('user_$userId');

      if (cached != null) {
        // Stale data is better than an error screen.
        // The user sees something useful even without internet.
        return User.fromJson(Map<String, dynamic>.from(cached));
      }

      // Nothing cached. We have no choice but to surface the error.
      rethrow;
    }
  }
}

Preserving User Input

This is the fix for the onboarding ticket I mentioned:

// Save whatever the user has typed whenever the field changes.
_contentController.addListener(() async {
  await _cache.put('draft_post', _contentController.text);
});

// When the screen opens, restore any saved draft.
@override
void initState() {
  super.initState();
  final draft = _cache.get('draft_post') as String?;
  if (draft != null && draft.isNotEmpty) {
    _contentController.text = draft;
  }
}

// Clear the draft once the user successfully submits.
Future<void> _submit() async {
  await _repository.createPost(_contentController.text);
  await _cache.delete('draft_post');
}

Three lines of code that save users from losing their work. This is worth doing in any form that takes more than a minute to fill out.

Packages I use for local persistence:

1. Hive for simple key-value storage

2. Isar when I need more powerful queries

3. sqflite for relational data

4. shared_preferences strictly for user settings, not for anything substantial

State Management at Scale

setState is fine. I want to say that clearly because there's a tendency in the Flutter community to treat it like it's always wrong. For local, simple UI state – a button toggling, a form field showing validation — setState is exactly the right tool.

The problems start when you use it for state that multiple widgets depend on, or for async operations, or for anything that needs to survive navigation. I've done all of these. Here's what goes wrong:

// This setState call lives high in the widget tree.
// Every widget below it rebuilds — including expensive ones
// that have nothing to do with this state change.
setState(() {
  currentUser = updatedUser;
});

As the app grows, this gets worse. Rebuilds spread. Side effects happen in unexpected order. You start spending more time debugging state than building features.

Moving to Riverpod

After hitting these walls in my second app, I switched to Riverpod and haven't looked back. The core idea is simple: state lives outside widgets, and widgets subscribe to exactly the state they need.

@riverpod
class UserNotifier extends _$UserNotifier {
  @override
  AsyncValue<User> build(String userId) {
    _load();
    return const AsyncValue.loading();
  }

  Future<void> _load() async {
    state = const AsyncValue.loading();

    // AsyncValue.guard runs the future and wraps the result
    // in AsyncValue.data on success or AsyncValue.error on failure.
    // It saves you from writing try/catch every single time.
    state = await AsyncValue.guard(
      () => ref.read(userRepositoryProvider).getUser(userId),
    );
  }

  Future<void> refresh() => _load();
}

In the widget:

@override
Widget build(BuildContext context) {
  // ref.watch subscribes this widget to the notifier.
  // It rebuilds only when userAsync changes — not when
  // unrelated state elsewhere in the app changes.
  final userAsync = ref.watch(userNotifierProvider(widget.userId));

  return userAsync.when(
    // when() forces you to handle loading, error, and data.
    // Miss one and it's a compile error, not a runtime surprise.
    loading: () => const CircularProgressIndicator(),
    error: (e, _) => Text('Error: $e'),
    data: (user) => UserProfileView(user: user),
  );
}

The part I appreciate most: when() makes it a compile error to forget the loading or error state. The compiler enforces what I used to forget.

Immutable State

One thing that burned me hard in a real-time chat feature: a mutable list shared across multiple parts of the app.

List<Message> messages = [];

// Later, in different places:
messages.add(newMessage);       // socket handler
messages.removeAt(0);          // pagination
messages.insert(0, pinned);    // push notification handler

When a message appeared twice, or disappeared at random, tracing which mutation caused it was genuinely painful. The fix is to never mutate and always create a new list:

// The old list is unchanged. The new state is a new list.
// Every change is explicit and traceable.
state = [...state, newMessage];

It feels like a small thing until you spend two hours debugging a mutation bug. Then it feels very important.

Widget Rebuilds and Rendering Performance

Flutter is fast. But unnecessary rebuilds accumulate, and on low-end devices the accumulation is noticeable.

Const Widgets Skip Rebuilds Entirely

The const keyword tells Dart this widget can be created at compile time and reused indefinitely. Any widget whose content will never change is a candidate.

// Without const: a new Text instance is created on every
// rebuild of the parent, even though the content never changes.
Text('Welcome to the app')

// With const: Flutter reuses the same instance.
// No rebuild work, no allocation.
const Text('Welcome to the app')

This sounds like a small thing. In a large widget tree with many static elements, the cumulative effect is real. Make it a habit.

Keep the Rebuild Scope Small

When setState lives high in the widget tree, every widget below it rebuilds — even ones that have nothing to do with the state that changed. The fix is to push state as far down the tree as possible, ideally into its own extracted widget.

// The problem: counter lives in the parent, so every
// setState call rebuilds the entire subtree — including
// ExpensiveListWidget, which has nothing to do with the counter.
class _BadExampleState extends State<BadExample> {
  int _counter = 0;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Count: $_counter'),
        ElevatedButton(
          onPressed: () => setState(() => _counter++),
          child: const Text('Increment'),
        ),
        const ExpensiveListWidget(), // rebuilds for no reason
      ],
    );
  }
}

Now, only that widget rebuilds when the count changes. ExpensiveListWidget is untouched.

ListView.builder for Anything of Unknown Length

A Column with a mapped list builds every item upfront regardless of whether it is visible. On a list of 200 items, that is 200 widgets created before the user has scrolled at all.

// This builds every single item widget upfront.
// With 200 items, 200 widgets are created on first render,
// most of which are immediately off-screen.
Column(
  children: items.map((item) => ItemCard(item: item)).toList(),
)

// This builds only what is visible, plus a small buffer.
// Scrolling through 10,000 items uses the same memory as 10.
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) {
    return ItemCard(items[index]);
  },
)

ListView.builder isn't an optimization for large lists. It's the correct default for any list of unknown or variable size. I use Column with a mapped list only when I know for certain the list will always be tiny.

Async Pitfalls and the Disposed Widget Problem

This is one of those bugs that's completely invisible during development and shows up constantly in production.

The scenario: an async operation starts, the user navigates away before it finishes, and the operation completes and tries to call setState on a widget that no longer exists.

Future<void> _loadData() async {
  final data = await repository.fetchData();

  // If the user navigated away during the await above,
  // this widget is gone. setState throws:
  // "setState() called after dispose()"
  setState(() => this.data = data );
}

The fix is one line:

Future<void> _loadData() async {
  final data = await repository.fetchData();

  // mounted is true while the widget is in the tree,
  // false after dispose() has been called.
  if (!mounted) return;

  setState(() => this.data = data);
}

I now write this check automatically after every await that leads to a setState. It becomes muscle memory quickly.

Never Create Futures Inside Build

This is an easy-to-overlook issue. When you create a Future directly inside the build method, a new Future is created on every rebuild — meaning FutureBuilder treats it as a brand new operation each time and resets to the loading state unnecessarily.

// Bad: a new Future is created on every rebuild.
// FutureBuilder sees a different Future each time
// and resets to loading state unnecessarily.
@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: repository.fetchUser(userId), // new Future every build
    builder: (context, snapshot) { ... },
  );
}

// Good: create the Future once in initState.
// FutureBuilder holds the same reference across rebuilds.
late final Future<User> _userFuture;

@override
void initState() {
  super.initState();
  _userFuture = repository.fetchUser(widget.userId);
}

@override
Widget build(BuildContext context) {
  return FutureBuilder(
    future: _userFuture,
    builder: (context, snapshot) { ... },
  );
}

Move Heavy Work Off the UI Thread

Dart renders UI on the main isolate. Anything CPU-intensive that blocks it causes dropped frames.

// Parsing a large API response synchronously on the main isolate
// can block rendering for 50-200ms on slower devices.
final users = (response.data as List)
    .map((json) => User.fromJson(json))
    .toList();

// compute() runs the function in a separate isolate.
// The main isolate stays free to render frames.
// Note: the function must be top-level or static —
// closures that capture local state cannot be sent to another isolate.
final users = await compute(parseUsers, response.data);

List<User> parseUsers(dynamic data) {
  return (data as List)
      .map((json) => User.fromJson(json as Map<String, dynamic>))
      .toList();
}

I reach for compute whenever I am parsing a large JSON response, doing image processing, or running anything that feels slow in a quick profile. The threshold in my head is roughly 16ms — if an operation might take longer than that, it shouldn't be on the main isolate.

Memory Leaks and Lifecycle Management

This one cost me the most debugging time across all the apps I've shipped. Memory leaks in Flutter don't crash immediately. They build slowly — a few megabytes per session, every session — until the app starts feeling heavy, the OS starts killing it in the background, and users file bug reports about "random crashes."

The root cause is almost always the same: something created inside a widget keeps running after the widget is gone.

Controllers That Are Never Disposed

The most common source of memory leaks I've seen, including in my own code, is controllers that are created in initState and never released. Flutter doesn't clean these up automatically.

class _ProfileScreenState extends State<ProfileScreen> {
  late final TextEditingController _nameController;
  late final AnimationController _fadeController;
  late final ScrollController _scrollController;

  @override
  void initState() {
    super.initState();
    _nameController = TextEditingController();
    _fadeController = AnimationController(
      vsync: this,
      duration: const Duration(milliseconds: 300),
    );
    _scrollController = ScrollController();
  }

  @override
  void dispose() {
    // Every controller created in initState needs to be
    // disposed here. This is not optional — it releases
    // native resources and removes listeners that would
    // otherwise keep this widget's memory alive indefinitely.
    _nameController.dispose();
    _fadeController.dispose();
    _scrollController.dispose();
    super.dispose(); // always last
  }
}

An undisposed AnimationController is particularly bad. It holds a ticker that fires on every frame — so it keeps consuming CPU even after the screen it belonged to is gone. I've seen this cause noticeable battery drain in addition to memory issues.

Stream Subscriptions

class _ChatScreenState extends State<ChatScreen> {
  StreamSubscription<Message>? _messageSubscription;

  @override
  void initState() {
    super.initState();
    _messageSubscription = messageStream.listen((message) {
      // Without cancellation, this callback keeps firing
      // even after the screen is removed from the tree.
      // It will call setState on a disposed widget and
      // hold message objects in memory that should be freed.
      if (mounted) setState(() => messages.add(message));
    });
  }

  @override
  void dispose() {
    _messageSubscription?.cancel();
    super.dispose();
  }
}

Timers

@override
void dispose() {
  // A timer that fires after dispose will try to run
  // a callback on a widget that no longer exists.
  _dismissTimer?.cancel();
  super.dispose();
}

A rule I follow without exception: anything created in initState that has a dispose, cancel, or close method gets a corresponding call in dispose. No exceptions, no "I'll add it later."

Observability and Crash Reporting

Before I integrated crash reporting into my first production app, debugging was genuinely painful. A user would report a crash. I would ask what they were doing. They would say "I just opened it." I would stare at the code looking for anything that could cause that. Half the time I never figured it out.

With crash reporting, that changes completely.

Set it Up Before Launch

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // Catch Flutter framework errors — widget build errors,
  // rendering errors, etc.
  FlutterError.onError =
      FirebaseCrashlytics.instance.recordFlutterFatalError;

  // Catch errors in async code that Flutter does not catch —
  // errors in event handlers, timers, isolates.
  PlatformDispatcher.instance.onError = (error, stack) {
    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    return true;
  };

  runApp(const MyApp());
}

Never Let Failures Be Silent

// This is how I used to write it. If submitOrder throws,
// nothing happens. The user has no idea. I have no idea.
await api.submitOrder(order);

// This is how I write it now.
try {
  await api.submitOrder(order);
  setState(() => orderStatus = OrderStatus.confirmed);
} catch (e, stackTrace) {
  // recordError sends the full exception and stack trace
  // to Crashlytics, with device info and the user's
  // recent session activity attached automatically.
  FirebaseCrashlytics.instance.recordError(e, stackTrace);
  setState(() => orderStatus = OrderStatus.failed);
}

Breadcrumbs

Raw crash logs tell you what broke. Breadcrumbs tell you what the user was doing when it broke. These aren't the same thing.

FirebaseCrashlytics.instance.log('User opened checkout');
FirebaseCrashlytics.instance.log('Payment sheet presented');
FirebaseCrashlytics.instance.log('User submitted payment');
// crash here — now I know the exact sequence

Testing Production Flutter Apps

I'll be honest: I under-tested my first app. I was moving fast, the features worked, and writing tests felt slow. Then I refactored a pricing calculation, introduced a bug that wasn't immediately obvious, and shipped it. A user caught it before I did.

I test more carefully now. Not everything — but the things that matter.

Unit Test Business Logic

test('discount applies percentage correctly', () {
  final result = calculateDiscountedPrice(
    price: 100.0,
    discountPercent: 10,
  );

  // 10% off 100.00 should be 90.00
  expect(result, equals(90.0));
});

test('discount throws for negative percentage', () {
  expect(
    () => calculateDiscountedPrice(price: 100, discountPercent: -5),
    throwsA(isA<ArgumentError>()),
  );
});

Business logic – pricing, validation, authorization – should be in plain Dart functions with no Flutter dependencies, so they can be tested in milliseconds without any test infrastructure.

Widget Test UI States

Flutter's widget testing is genuinely one of its best features. You can test loading states, error states, and user interactions without a device or emulator.

testWidgets('shows error state with retry button on load failure',
    (tester) async {
  final mockRepo = MockUserRepository();
  when(mockRepo.getUser(any)).thenThrow(Exception('Network error'));

  await tester.pumpWidget(
    ProviderScope(
      overrides: [
        userRepositoryProvider.overrideWithValue(mockRepo),
      ],
      child: const MaterialApp(home: ProfileScreen(userId: 'test')),
    ),
  );

  // pumpAndSettle waits for all animations and async
  // operations to complete before asserting.
  await tester.pumpAndSettle();

  expect(find.text('Failed to load profile. Please try again.'), findsOneWidget);
  expect(find.text('Try again'), findsOneWidget);
});

What I prioritize testing: core business logic, error and loading states, any flow that involves money or data the user can't recover, and the integration points between my app and the backend. Static UI widgets that contain no logic I generally leave uncovered.

Architecture and Long-Term Maintainability

The first app I shipped had no real architecture. Everything was in widgets. Business logic sat next to UI code. State was scattered.

It worked fine for six months. Then I needed to add a feature that touched several existing screens, and what should have taken a day took a week because I couldn't change anything without breaking something else.

The second app I was more deliberate about. Features in their own folders. Repositories separate from widgets. State managed outside the UI layer. When requirements changed — and they always change — the changes were contained.

Separate Concerns at the Layer Boundary

lib/
  features/
    profile/
      data/
        profile_repository.dart     # network + cache logic
      domain/
        user.dart                   # clean domain model
      presentation/
        profile_screen.dart         # widget
        profile_notifier.dart       # state

Widgets shouldn't make network calls. Repositories shouldn't import Flutter. Neither should know anything about the other's internals.

When you need to swap the data source, or test the notifier with a mock, or change the UI without touching the business logic — this separation is what makes that possible.

Technical Debt Accumulates Faster Than You Expect

A shortcut that saves thirty minutes today tends to cost several hours a month from now. The shortcuts that compound fastest in Flutter:

• Business logic inside widgets (impossible to test, impossible to reuse)

• dynamic instead of typed models (runtime errors instead of compile-time errors)

• Copy-pasted validation logic (change it in one place and forget the others)

• Mutable global state without clear ownership

None of these are catastrophic on day one. All of them make the next change harder than it should be, and the change after that harder still.

End-to-End Example: a Production-Grade Profile Feature

Here's everything from this article assembled into one feature. A repository with caching and retry, a Riverpod notifier with optimistic updates, a widget that handles all three states, and proper lifecycle management throughout.

The Repository

class ProfileRepository {
  final Dio _dio;
  final Box _cache;

  ProfileRepository(this._dio, this._cache);

  Future<User> getUser(String userId) async {
    try {
      final response = await withRetry(
        () => _dio.get('/users/$userId'),
      );

      final user = User.fromJson(
        response.data as Map<String, dynamic>,
      );

      // Cache successful responses for offline fallback.
      await _cache.put('user_$userId', user.toJson());

      return user;
    } on DioException catch (e) {
      final cached = _cache.get('user_$userId');

      if (cached != null) {
        return User.fromJson(Map<String, dynamic>.from(cached));
      }

      if (e.type == DioExceptionType.connectionError) {
        throw NoInternetException();
      }

      throw ServerException(e.response?.statusCode ?? 0);
    }
  }

  Future<void> updateDisplayName(String userId, String name) async {
    await withRetry(
      () => _dio.patch('/users/$userId', data: {'displayName': name}),
    );

    // Invalidate cache so the next read fetches fresh data.
    await _cache.delete('user_$userId');
  }
}

The Notifier

@riverpod
class ProfileNotifier extends _$ProfileNotifier {
  @override
  AsyncValue<User> build(String userId) {
    _load();
    return const AsyncValue.loading();
  }

  Future<void> _load() async {
    state = const AsyncValue.loading();
    state = await AsyncValue.guard(
      () => ref.read(profileRepositoryProvider).getUser(userId),
    );
  }

  Future<void> refresh() => _load();

  Future<void> updateName(String newName) async {
    final current = state.valueOrNull;
    if (current == null) return;

    try {
      await ref
          .read(profileRepositoryProvider)
          .updateDisplayName(userId, newName);

      // Update the UI immediately without waiting for a reload.
      state = AsyncValue.data(current.copyWith(displayName: newName));
    } catch (e, st) {
      FirebaseCrashlytics.instance.recordError(e, st);
      // Restore the previous state if the update fails.
      state = AsyncValue.data(current);
      rethrow;
    }
  }
}

The Widget

class ProfileScreen extends ConsumerWidget {
  final String userId;
  const ProfileScreen({required this.userId, super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final profileAsync = ref.watch(profileNotifierProvider(userId));

    return Scaffold(
      appBar: AppBar(title: const Text('Profile')),
      body: profileAsync.when(
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (e, _) => _ErrorView(
          message: e is NoInternetException
              ? 'No internet connection.'
              : 'Failed to load profile.',
          onRetry: () => ref
              .read(profileNotifierProvider(userId).notifier)
              .refresh(),
        ),
        data: (user) => _ProfileView(user: user, userId: userId),
      ),
    );
  }
}

class _ProfileView extends ConsumerStatefulWidget {
  final User user;
  final String userId;
  const _ProfileView({required this.user, required this.userId});

  @override
  ConsumerState<_ProfileView> createState() => _ProfileViewState();
}

class _ProfileViewState extends ConsumerState<_ProfileView> {
  late final TextEditingController _nameController;

  @override
  void initState() {
    super.initState();
    _nameController = TextEditingController(text: widget.user.displayName);
  }

  @override
  void dispose() {
    _nameController.dispose();
    super.dispose();
  }

  Future<void> _saveName() async {
    try {
      await ref
          .read(profileNotifierProvider(widget.userId).notifier)
          .updateName(_nameController.text);

      if (!mounted) return;

      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Name updated.')),
      );
    } catch (_) {
      if (!mounted) return;

      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Failed to update name.')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return ListView(
      padding: const EdgeInsets.all(16),
      children: [
        TextField(
          controller: _nameController,
          decoration: const InputDecoration(labelText: 'Display name'),
        ),
        const SizedBox(height: 16),
        ElevatedButton(
          onPressed: _saveName,
          child: const Text('Save'),
        ),
      ],
    );
  }
}

Final Thoughts

None of this is particularly advanced. It's mostly habits — checking mounted, disposing controllers, handling the error state, caching for offline. Each habit prevents one specific category of production failure, and together they add up to an app that users experience as reliable.

I wish I'd written my first app this way. I didn't, because I didn't know what I didn't know yet. That is normal.

But if you're reading this before shipping your first production app, you now have the benefit of what took me multiple shipped apps and a lot of frustrated user feedback to learn.

The best time to add these patterns is at the start of a feature. The second-best time is now.

Yet despite its impressive performance, GPT-3 revealed an important limitation: raw capability doesn't automatically create a useful assistant.

A language model can generate fluent text, answer questions, and solve complex tasks while still failing to follow what the user actually wants.

GPT-3 could produce responses that were inconsistent, overly confident, difficult to control, or misaligned with user instructions. It was a powerful prediction engine, but it wasn't designed to reliably act as a helpful assistant.

This challenge motivated one of the most influential papers in modern AI: Training Language Models to Follow Instructions with Human Feedback. Rather than making the model larger, the researchers focused on teaching it how to better follow human intent.

The result was InstructGPT, a system fine-tuned from GPT-3 that demonstrated how human feedback could transform a capable language model into a far more useful and aligned assistant.

This challenge became one of the most important problems in modern AI: alignment.

Researchers realized that building larger models was only part of the solution. While scaling improved capabilities, it didn't guarantee that models would reliably follow instructions or behave in ways that matched user expectations. The next stage of progress required teaching models how to respond in a more helpful, truthful, and safe manner.

This led to the development of instruction-following systems and Reinforcement Learning from Human Feedback (RLHF). Instead of optimizing models solely to predict the next word, researchers began training them to better align with human preferences and intentions.

This shift marked a major turning point in the evolution of large language models.

GPT-3 demonstrated the power of large-scale language modeling and introduced many people to prompting and few-shot learning.

InstructGPT built on that foundation by showing how human feedback could significantly improve instruction following and model behavior. ChatGPT then brought these ideas to a much broader audience by packaging aligned language models into an accessible conversational interface used by millions of people.

In many ways, language models became capable before they became aligned.

That's why the transition from GPT-3 to InstructGPT represents one of the most important milestones in the history of artificial intelligence. The focus was no longer only on making models more capable. It was also about making them more useful, reliable, and responsive to human intent.

The success of InstructGPT pioneered many of the alignment techniques that later became a core part of systems such as ChatGPT and GPT-4.

Paper Overview:

In this article, we’ll mainly focus on the paper Training Language Models to Follow Instructions with Human Feedback, published by OpenAI in 2022.

This paper introduced InstructGPT, one of the most important transitions in the history of large language models. While earlier GPT systems focused heavily on scaling model size and improving raw capabilities, this work shifted attention toward something equally important: alignment.

The paper explores how language models can be trained to better follow human instructions using reinforcement learning from human feedback (RLHF). Instead of optimizing only for next-token prediction, the model is further optimized to produce responses that humans actually prefer – responses that are more helpful, safer, and more aligned with user intent.

What makes this paper historically important is that it became the foundation for the modern ChatGPT alignment pipeline.

Many of the interaction patterns people now associate with ChatGPT (like instruction following, conversational behavior, refusal handling, and safer responses) can be traced directly back to the ideas introduced here.

Here’s the original paper again if you want to explore it directly: Training language models to follow instructions with human feedback

And here’s a quick infographic of what we’ll cover throughout this review:

Table of Contents:

• Executive Summary

• The Core Problem

• Why GPT-3 Was Not Enough

• InstructGPT: The Birth of Alignment-Centered LLMs

• RLHF Pipeline: How InstructGPT Learned to Behave Like an Assistant

  • Stage 1 — Supervised Fine-Tuning (SFT)

  • Stage 2 — Reward Model Training

  • Stage 3 — PPO Reinforcement Learning

• Helpful, Honest, Harmless

• Human Feedback as the New Scaling Factor

• Why ChatGPT Exploded Globally

• ChatGPT as an Interface Revolution

• Benchmarks and Results

• Truthfulness and Hallucinations

• Safety and Refusal Behavior

• Limitations

• Historical Importance

• Discussion: The Real Shift

• Connection to GPT-4

• GPT-3 vs InstructGPT vs ChatGPT vs GPT-4: Key Differences

• From GPT-1 to GPT-4: A Timeline of Modern AI Systems and Alignment Evolution

• Final Insight

• Resources

Prerequisites

To get the most out of this breakdown, it helps to already be familiar with a few foundational ideas.

Reading the previous reviews in this series will be especially helpful:

• AI Paper Review: Improving Language Understanding by Generative Pre-Training (GPT-1)

• AI Paper Review: Language Models are Unsupervised Multitask Learners (GPT-2)

• AI Paper Review: Language Models are Few-Shot Learners (GPT-3)

Even though GPT-4 was released after InstructGPT, reading the GPT-4 review can still be helpful. It provides a broader view of how alignment techniques evolved and how they were combined with stronger reasoning and multimodal capabilities in later generations of GPT models.

• AI Paper Review: GPT-4 Technical Report (GPT-4)

It also helps to have:

• A general understanding of natural language processing (NLP) and large language models

• A high-level idea of Transformer-based autoregressive models

• Familiarity with prompting, few-shot learning, and in-context learning

• A basic understanding of reinforcement learning and human feedback systems

• General machine learning concepts like training data, fine-tuning, scaling, and inference

• Some familiarity with alignment, safety, and AI behavior control concepts

You don't need to be an AI researcher to follow this article, though.

I’ll keep the explanations practical and intuitive, focusing more on understanding how InstructGPT changed modern AI systems rather than getting lost in dense mathematical details or academic terminology.

Executive Summary

The paper Training Language Models to Follow Instructions with Human Feedback marks one of the biggest turning points in the history of modern AI systems. Instead of asking only how to make language models larger or smarter, OpenAI focused on a different question: how do we make these models actually helpful for real people?

The paper introduces InstructGPT, a version of GPT-3 fine-tuned to follow human instructions more accurately using a method called Reinforcement Learning from Human Feedback (RLHF).

The core insight of the paper is simple but extremely important:

Bigger language models don't automatically become better assistants.

Even highly capable models like GPT-3 could still:

• ignore instructions

• hallucinate facts

• generate toxic or biased outputs

• produce responses that were technically fluent but not actually useful to users

To solve this problem, OpenAI built a multi-stage alignment pipeline: humans first demonstrate ideal answers, humans then rank model outputs, and finally the model learns from those preferences using reinforcement learning.

This changed the direction of modern AI development.

The paper shows that alignment and usability can matter more than raw model size itself. One of the most surprising findings was that the 1.3B InstructGPT model was often preferred by human evaluators over the original 175B GPT-3 model, despite being dramatically smaller.

The paper also demonstrates improvements in instruction following, truthfulness, toxicity reduction, conversational behavior, and general user preference.

Historically, this paper became the foundation behind modern conversational AI systems.

GPT-3 proved that language models could learn from prompts.

GPT-4 later proved that scaling and multimodal reasoning could unlock even stronger capabilities.

But InstructGPT showed something equally important: AI systems must be aligned with human intent to become truly usable products.

In many ways, this paper represents the transition from raw language modeling to aligned assistants, capability scaling to behavior shaping, and research demos to real-world conversational AI systems.

And that transition eventually led directly to ChatGPT.

The Core Problem

One of the most important ideas in this paper is that raw language modeling is not the same thing as building a useful assistant.

Before InstructGPT, models like GPT-3 were trained mainly with a simple objective: predict the next token in a sequence.

That objective made language models extremely powerful at generating fluent text, but it also created a major limitation. The model learned how to continue internet text, not necessarily how to help humans.

This became one of the defining realizations behind modern AI alignment research.

Despite its impressive capabilities, GPT-3 often struggled to behave like a reliable assistant. The model could produce fluent text, but it was not explicitly trained to follow user intent.

Here are some examples that highlight the differences between GPT-3 and InstructGPT in how they respond to user prompts:

Source: Aligning language models to follow instructions

Source: Aligning language models to follow instructions

These examples reveal the central weakness of early GPT systems. GPT-3 often continued the pattern of the prompt rather than completing the requested task. InstructGPT, by contrast, responded directly to the user's instruction. The difference wasn't a matter of raw intelligence. It was a difference in training objectives.

GPT models were trained on massive internet-scale datasets where the goal was simply to predict what text comes next. As a result, the model optimized for plausibility, continuation, and pattern completion. Not necessarily for truthfulness, safety, helpfulness, or alignment with human goals.

This created a major gap between: language capability and useful assistant behavior.

For example, if a user asked a harmful, misleading, or nonsensical question, the model might still attempt to continue the pattern naturally instead of recognizing the issue. In many cases, the model behaved more like an internet text simulator than a reliable assistant.

The paper repeatedly emphasizes that scaling alone couldn't solve this problem.

Researchers increasingly recognized that better behavior would require more than scaling alone.

Models also needed stronger instruction following, better alignment with human intent, improved safety behavior, greater truthfulness, and optimization around real user needs.

Why GPT-3 Was Not Enough

When GPT-3 was released, it felt like a massive leap forward in AI capabilities.

The model could perform few-shot learning, answer questions, summarize text, generate code, translate languages, and even solve certain reasoning tasks: all without traditional fine-tuning. For many researchers, it was the first time a language model started to feel genuinely general-purpose.

Yet using GPT-3 in practice was often less reliable than its benchmark performance suggested.

In practice, using GPT-3 often required careful prompt engineering. Small wording changes could completely change the quality of the response. Sometimes the model followed instructions well, and other times it ignored them entirely.

Users often found themselves rewriting prompts repeatedly to obtain the response they actually wanted.

This became the core motivation behind InstructGPT.

OpenAI responded by exploring ways to make model behavior more consistent, predictable, and useful for users.

InstructGPT: The Birth of Alignment-Centered LLMs

The release of InstructGPT marked one of the biggest shifts in the history of large language models.

Before InstructGPT, most advances in language models came from scaling data, compute, and model size.

The focus shifted toward alignment: building systems that could follow instructions more reliably and behave in ways users actually preferred.

This is where InstructGPT introduced one of the most important ideas in modern AI systems: Reinforcement Learning from Human Feedback (RLHF).

Instead of optimizing models only to predict internet text, OpenAI started optimizing models based on what humans actually preferred. Human labelers ranked model outputs, and those preferences became part of the training process itself.

This fundamentally changed the objective of language models.

Rather than optimizing solely for next-token prediction, the system was increasingly optimized to produce responses that humans judged to be helpful, safe, and aligned with their intentions.

That distinction may sound subtle, but it completely changed the direction of AI development.

InstructGPT combined instruction-following training with human preference optimization, creating a model whose behavior could be shaped directly through feedback rather than solely through pretraining.

The model was no longer trained only to imitate the internet. It was trained to behave more like an assistant.

RLHF Pipeline: How InstructGPT Learned to Behave Like an Assistant

At the center of the InstructGPT paper is a training pipeline that completely changed how modern AI assistants are built.

RLHF was designed to build on traditional language-model pretraining rather than replace it.

The InstructGPT paper introduced a different idea: instead of training models only on internet text, why not train them using human preferences directly?

This led to the development of the RLHF pipeline: Reinforcement Learning from Human Feedback. This approach would later become a standard component of modern conversational AI systems.

The paper’s Figure 2 is especially important because it visualizes the entire alignment pipeline introduced by OpenAI. Rather than relying on a single training stage, the system uses multiple stages where human feedback gradually shapes model behavior.

Source: Training Language Models to Follow Instructions with Human Feedback (OpenAI, 2022).

As you can see in the image above, the process happens in three major stages.

Stage 1 — Supervised Fine-Tuning (SFT)

The first stage starts with human-written demonstrations.

Labelers are given prompts and asked to write ideal responses – the kinds of answers a helpful assistant should produce. These examples become the initial training dataset for the model.

At this stage, the model learns the basic patterns of assistant-style responses.

This is still traditional supervised learning, but the goal is different from standard language modeling. Instead of learning only from web text, the model now learns from examples of preferred assistant behavior.

This stage creates what the paper calls the Supervised Fine-Tuned model (SFT model).

And while this already improves behavior significantly, OpenAI realized something important: human preferences are more complex than simple “correct answers.”

There are often many possible responses to a prompt, but humans may strongly prefer some answers over others.

That leads to the next stage.

Stage 2 — Reward Model Training

In the second stage, humans no longer write responses directly.

Instead, the model generates multiple answers for the same prompt, and human labelers rank them from best to worst.

For a given prompt, one response may be clearer, another more accurate, and another safer or more appropriate. Human labelers rank these alternatives according to their preferences

The rankings are then used to train a separate neural network called the Reward Model (RM).

This model learns something extremely important: which outputs humans prefer.

In other words, the system converts human preferences into a trainable reward signal.

This becomes one of the biggest conceptual breakthroughs in the paper. Instead of manually programming behavior rules, OpenAI trains the model to approximate human judgment itself.

The reward model captures patterns in human preferences and turns them into a training signal.

That reward signal becomes the foundation for the final training stage.

Stage 3 — PPO Reinforcement Learning

The final stage uses reinforcement learning to optimize the language model against the reward model.

More specifically, the paper uses PPO (Proximal Policy Optimization), a reinforcement learning algorithm commonly used in policy optimization tasks.

At this stage, the model generates responses, receives scores from the reward model, and gradually updates its behavior to maximize those scores.

The model gradually shifts toward responses that receive higher scores from the reward model.

The key innovation is that optimization now occurs against a learned representation of human preferences rather than only a language-modeling objective.

According to the paper, this RLHF pipeline significantly improved instruction following and user preference ratings while also reducing toxic and unsafe behavior.

And in many ways, this pipeline became the blueprint for the modern era of conversational AI systems.

Helpful, Honest, Harmless

The authors argue that evaluating language models requires more than measuring capability alone. They should also be evaluated by how they behave around humans.

At the time, this represented a significant shift in how researchers evaluated language models.

That is why the paper repeatedly emphasizes a new alignment philosophy centered around three goals:

• Helpful

• Honest

• Harmless

These ideas became the conceptual foundation behind modern alignment research and conversational AI systems.

Helpful

The first goal is straightforward: the model should genuinely help the user accomplish what they want.

In practice, helpfulness means following instructions clearly, answering questions directly, providing relevant information, and adapting to the user's intent.

This may seem simple, but it fundamentally changes the training objective.

The model is no longer optimized only for linguistic fluency. It's optimized for usefulness.

Honest

The second goal is honesty.

One of the biggest problems with large language models is that they often produce convincing answers even when those answers are wrong. The models can hallucinate facts, invent references, or respond confidently despite uncertainty.

The paper recognizes that a useful assistant shouldn't merely sound intelligent. It should also behave truthfully and acknowledge uncertainty when necessary.

This is especially important because language models are optimized to generate plausible text, not verified truth.

As a result, earlier models sometimes prioritized sounding coherent over being accurate.

The alignment process introduced in InstructGPT attempts to reduce this behavior through human feedback and preference optimization. Human evaluators consistently prefer responses that are more accurate, transparent, and reliable, and those preferences gradually shape the model during RLHF training.

The paper doesn't claim that hallucinations disappear completely. Far from it. But it marks one of the first large-scale attempts to explicitly optimize language models for truthfulness and reliability rather than pure text generation quality.

Harmless

The third goal is harmlessness.

Large language models trained on internet data inevitably absorb toxic, biased, unsafe, or harmful patterns from that data. Without alignment, models may generate dangerous instructions, offensive content, or manipulative behavior.

The paper directly addresses this concern and treats safety as a central part of model development.

Through RLHF and human preference ranking, the model learns to refuse certain harmful requests, avoid toxic generations, produce safer responses, and behave more responsibly during interaction.

This became one of the defining characteristics of modern conversational AI systems.

Instead of maximizing unrestricted generation, the system begins balancing usefulness, safety, and alignment with human values.

But the paper is also honest about limitations.

The authors acknowledge that harmful outputs, biases, and unsafe behavior can still appear. Alignment is imperfect, and human values themselves are complex and difficult to define universally.

But historically, this paper marks the moment when safety and alignment became core engineering goals rather than secondary concerns.

Taken together, these three principles (helpful, honest, and harmless) became much more than training objectives. They became the philosophical foundation behind ChatGPT-era AI systems.

Earlier GPT papers mainly explored how to scale intelligence. But InstructGPT explored something deeper: how to make intelligence usable for humans.

Human Feedback as the New Scaling Factor

One of the most fascinating ideas behind the InstructGPT paper is that it quietly changed what “scaling” meant in modern AI.

For years, progress in language models was largely measured through scaling.

GPT-1 showed that pretraining works. GPT-2 showed that larger models develop stronger zero-shot behavior. GPT-3 pushed this idea even further by scaling to 175 billion parameters and demonstrating impressive few-shot learning abilities.

And to some extent, that was true. Larger models became better at reasoning, code generation, language understanding, translation, and generalization.

That is where human feedback became central.

Instead of relying purely on internet-scale text, OpenAI introduced a training pipeline where human preferences directly shaped model behavior. Human labelers ranked responses, evaluated quality, and guided the system toward outputs people actually preferred.

In many ways, this created a completely new scaling dimension for AI systems:

• scaling human feedback

• scaling preference learning

• scaling alignment pipelines

Historically, this shifted attention from model scale alone toward the quality of model behavior

InstructGPT focused on scaling usability. And the results were surprisingly powerful.

According to the paper, a much smaller aligned model was often preferred over the original 175B GPT-3 model by human evaluators.

That finding changed how the industry thought about progress.

The result suggested that improving behavior could sometimes matter as much as increasing scale.

This is why RLHF became one of the defining ideas of the ChatGPT era.

After InstructGPT, modern AI systems were no longer evaluated only by benchmark scores, parameter counts, or scaling curves.

They were increasingly evaluated by usefulness, conversational quality, safety, reliability, and how well they interact with humans.

And that shift fundamentally changed the future direction of large language models.

Why ChatGPT Exploded Globally

When ChatGPT launched publicly, the reaction was immediate and unlike anything the AI industry had seen before.

Millions of people started using it within days. Developers, students, writers, researchers, businesses, and everyday users suddenly felt like they were interacting with AI in a completely different way.

What made this moment so important was that advanced AI capabilities finally became accessible to ordinary users. After all, the underlying language models were already extremely capable before ChatGPT existed. GPT-3 could generate essays, answer questions, write code, summarize text, and perform impressive few-shot learning tasks. GPT-4 later pushed reasoning and multimodal abilities even further.

The challenge was no longer whether language models could perform useful tasks, but whether people could interact with them naturally.

ChatGPT combined powerful language-model capabilities with RLHF-based alignment, conversational interaction, safer behavior, and a user-friendly chat interface.

Earlier systems often required significant prompt experimentation to achieve consistent results. Users had to carefully engineer prompts, retry questions, or work around strange outputs. The models could be brilliant one moment and confusing the next.

ChatGPT changed that experience dramatically.

Thanks to the alignment techniques introduced in the InstructGPT paper, the system became far better at following instructions, maintaining conversational flow, understanding intent, and responding in a way that felt cooperative rather than purely generative.

The conversational interface itself also mattered enormously.

Before ChatGPT, interacting with advanced AI systems often required APIs, coding knowledge, prompt experimentation, or technical understanding.

ChatGPT simplified everything into a familiar chat format: you simply typed naturally, and the system responded naturally.

That design decision may sound small, but historically it was transformative. It turned large language models from research tools into consumer products.

Although imperfect, the system felt substantially more reliable than earlier language-model interfaces.

The system was designed to communicate in ways that felt more natural and cooperative.

The breakthrough was not simply that the AI became smarter. The breakthrough was that the AI became usable.

And that usability is what transformed large language models from impressive research demonstrations into globally adopted AI assistants.

ChatGPT as an Interface Revolution

One of the most important things about ChatGPT is that it changed how humans interact with computers.

Before ChatGPT, powerful AI systems mostly lived behind APIs, research demos, developer tools, and complex prompting workflows.

Using advanced language models often required technical knowledge. Developers experimented with prompt engineering, API parameters, temperature settings, and carefully structured inputs just to get reliable outputs from the model.

Even GPT-3, despite being extremely powerful, still felt like a research system for many users. You had to learn how to “talk to the model.”

And in many cases, the interaction felt fragile. Slight changes in wording could completely change the quality of the response.

ChatGPT changed that dynamic almost overnight.

Instead of making users adapt to the AI, the AI became much better at adapting to humans.

Natural conversation became the interface.

For decades, human-computer interaction depended on commands, menus, search boxes, forms, programming languages, and specialized software interfaces.

ChatGPT introduced something different: you could simply explain what you wanted in plain language. And the system would usually understand.

This made AI feel accessible to people who had never written code, used APIs, or interacted with machine learning systems before.

In many ways, ChatGPT transformed prompting into a universal interface for computing. And that single shift affected nearly every digital field.

In education, students started using conversational AI to explain difficult concepts, summarize lessons, practice languages, and receive tutoring-style help.

In coding, developers began using AI systems for debugging, code generation, documentation, and learning new frameworks.

This eventually led to the rise of AI coding assistants integrated directly into development environments.

In writing and content creation, conversational AI became a brainstorming partner capable of drafting ideas, rewriting text, organizing articles, and helping people communicate more effectively.

Search behavior also started changing. Instead of searching through lists of links, users increasingly expected direct conversational answers. This fundamentally challenged traditional search-engine interaction models.

And across productivity tools, AI systems began acting less like software features and more like collaborative assistants.

This shift was enabled by advances in conversational AI and interaction design that made dialogue feel natural and useful.

The alignment techniques introduced by InstructGPT were an important part of making these conversational experiences practical.

Historically, this may become one of the most important consequences of the GPT era: earlier software required humans to learn interfaces. ChatGPT pushed computing toward interfaces that learn humans instead.

Benchmarks and Results

We've already discussed how one of the biggest improvement didn't come from making the model larger. Instead, it came from making the model better aligned with humans.

This is one of the central findings of the entire paper, and it changed how many researchers thought about progress in large language models.

Before this work, the dominant belief was that scaling was the main path forward, with bigger models, more parameters, more compute, and more data. And GPT-3 seemed to confirm that idea. Larger models consistently showed stronger few-shot learning, reasoning, and generalization abilities.

But the InstructGPT paper introduced a different perspective. The researchers found that a relatively small 1.3B parameter InstructGPT model was often preferred by human evaluators over the original 175B GPT-3 model.

That result was extremely important. It suggested that alignment sometimes outperformed scale.

This became one of the defining insights of the ChatGPT era.

According to the paper, human evaluators consistently preferred InstructGPT responses because they were more helpful, more accurate, safer, and better aligned with what users were actually asking for.

The improvements appeared across several important areas.

One major improvement was instruction following. Earlier GPT models often ignored instructions, drifted off-topic, or generated responses that sounded fluent but failed to solve the user’s actual task. InstructGPT behaved much more like a cooperative assistant and followed prompts more reliably.

The paper also reports improvements in truthfulness. Large language models are known for hallucinating information and confidently generating false statements. Through RLHF and preference optimization, InstructGPT reduced some of these behaviors and produced answers humans judged to be more truthful and reliable.

Another important improvement involved toxicity and harmful outputs. The researchers evaluated the system on toxicity benchmarks and found that aligned models generated fewer toxic or unsafe responses compared to earlier GPT systems.

What makes these findings historically important is that they changed the industry’s understanding of what “better AI” actually meant.

Before InstructGPT, improvement was mostly measured through benchmark scores, scaling curves, and parameter counts.

After InstructGPT, researchers increasingly focused on usability, safety, alignment, conversational quality, and human preference satisfaction.

This was a major shift in AI development philosophy.

Truthfulness and Hallucinations

A major challenge for language models is that fluent responses are not always truthful.

This behavior is now commonly called hallucination.

Hallucinations can take many forms, including invented facts, fabricated references, incorrect explanations, or confident answers that lack factual support.

And because the responses are fluent and natural, the mistakes can sometimes look believable to users. The InstructGPT paper treats this as a serious issue rather than a minor flaw.

The authors note that language models are optimized for plausibility rather than verified truth. This is an important distinction: a language model can generate text that looks correct while still being inaccurate.

This is why the paper places particular emphasis on truthfulness and factual reliability.

Through RLHF and human preference optimization, InstructGPT was trained to produce answers humans judged to be more accurate and trustworthy. Human evaluators generally preferred responses that were more transparent about uncertainty and less likely to contain misleading information.

The paper also evaluates the model on truthfulness benchmarks such as TruthfulQA, where aligned models demonstrated improvements compared to earlier GPT systems.

But the paper is also careful not to overstate the results. Hallucinations didn't disappear. The aligned models could still make reasoning mistakes, generate false information, misunderstand prompts, or produce overconfident answers.

This nuance is extremely important: the paper doesn't claim that RLHF solved factuality or reasoning completely. Instead, alignment improved behavior, not perfection.

That distinction became increasingly important as ChatGPT and later GPT-4 systems reached millions of users worldwide.

The models became more useful, more truthful, and more aligned, but they still remained probabilistic language models rather than guaranteed fact engines.

In many ways, the InstructGPT paper marks the beginning of large-scale efforts to make AI systems not only intelligent, but also trustworthy enough for real-world human interaction.

Safety and Refusal Behavior

As language models became more powerful, researchers realized that safety was becoming a deployment problem.

A model that can generate human-like language at scale can also generate harmful instructions, produce toxic content, spread misinformation, or be manipulated into unsafe behavior.

The InstructGPT paper treats these risks very seriously and frames alignment as a necessary part of deploying large language models responsibly.

One of the biggest changes introduced through RLHF was safer refusal behavior.

Earlier GPT systems often attempted to answer almost anything. As a result, they often responded to unsafe prompts rather than recognizing when a refusal was appropriate.

InstructGPT begins changing that behavior.

Through human feedback and preference optimization, the model learns that some requests shouldn't be answered directly. Human labelers consistently prefer safer responses, refusals for harmful instructions, and outputs that avoid dangerous or toxic behavior.

This leads to systems that are better at refusing unsafe requests, avoiding toxic generations, and behaving more cautiously during interaction.

The paper also evaluates toxicity reduction using safety-related benchmarks and finds that aligned models generally produce fewer harmful outputs than earlier GPT systems.

Another important issue is harmful content filtering. Large language models absorb patterns from massive internet datasets, which inevitably contain biased language, misinformation, unsafe instructions, and toxic behavior.

Without alignment, models may reproduce these patterns surprisingly easily.

RLHF acts as a corrective layer on top of pretraining. Instead of only imitating internet text, the model is further optimized toward responses humans judge to be safer and more appropriate.

Of course, the paper is also realistic about limitations.

The authors acknowledge that alignment is incomplete and that unsafe outputs can still occur. Models may still be vulnerable to adversarial prompting or attempts to bypass safety behavior (what later became widely known as jailbreaks).

This is an important nuance: alignment reduces risk, but it doesn't eliminate it.

And historically, this realization became incredibly important for the future of large-scale AI deployment.

In many ways, the InstructGPT paper marks the beginning of modern AI safety engineering inside flagship language models.

InstructGPT introduced large-scale behavior alignment. Then GPT-4 expanded this even further with red teaming, adversarial testing, deployment monitoring, and much larger safety evaluation pipelines.

So this paper becomes a direct bridge between early generative language models and the much more safety-focused AI systems that followed in the GPT-4 era.

Limitations

One of the strongest aspects of the InstructGPT paper is that it doesn't present alignment as a solved problem.

Even though the results are impressive, the authors are careful and surprisingly honest about the system’s remaining weaknesses and risks.

This balance is important because the paper isn't arguing that RLHF creates perfect AI systems. The authors consistently frame alignment as a work in progress rather than a finished solution.

One major limitation is that the models still hallucinate.

The paper acknowledges that hallucinations remain a significant challenge despite alignment improvements.

RLHF improves truthfulness and instruction adherence, but it doesn't fundamentally solve the probabilistic nature of language models. The system still predicts likely text patterns rather than verifying objective truth.

Another important issue is reward hacking.

Because the model is optimized against a learned reward signal, it can sometimes discover shortcuts that maximize reward without genuinely improving reasoning or understanding. In other words, the model may learn behaviors that look aligned to evaluators while still hiding deeper problems underneath.

This is a common challenge in reinforcement learning systems more broadly.

The paper also hints at a problem that later became widely discussed in ChatGPT-era systems: over-refusal and sycophancy.

Sometimes aligned models become too cautious and refuse harmless requests unnecessarily. In other cases, models may become overly agreeable, telling users what they appear to want to hear instead of providing more balanced or truthful responses.

This creates a difficult tension between safety, helpfulness, and honesty.

Another major limitation is bias.

Since these systems are trained on massive internet datasets and further shaped through human labeling, they inevitably inherit biases from both sources. The paper explicitly acknowledges that alignment doesn't remove all harmful or biased behavior.

And perhaps most importantly, the paper emphasizes that RLHF aligns models to labeler preferences not universal human values. This is a very important nuance.

The system learns from the judgments of specific human annotators operating within specific cultural and organizational contexts. That means alignment itself is subjective and imperfect.

There is no single universally agreed definition of helpfulness, fairness, safety, or acceptable behavior.

The paper discusses these concerns carefully and recognizes that human feedback introduces its own limitations and assumptions.

The alignment itself is also fragile. Even aligned systems can sometimes be manipulated through adversarial prompting or jailbreak-style attacks that bypass safety behavior. This later became one of the defining challenges of ChatGPT and GPT-4 deployment.

And finally, there's the practical issue of scale.

RLHF requires large amounts of human labeling, ranking, evaluation, and monitoring. Building these alignment pipelines is expensive, time-consuming, and operationally complex. Unlike raw pretraining data scraped automatically from the internet, human feedback doesn't scale nearly as easily.

In many ways, the paper reveals an important truth about modern AI systems: making models intelligent is difficult. But making them reliably aligned with humans may be even harder.

Historical Importance

Looking back now, it's difficult to overstate how important the InstructGPT paper became for the entire AI industry.

Earlier GPT papers focused mostly on one central question: How do we make language models more capable?

That era was largely driven by larger datasets, larger parameter counts, scaling laws, and benchmark performance.

The models became increasingly impressive at generating text, solving tasks, and demonstrating emergent abilities. But they still behaved primarily like prediction engines trained to continue internet text.

InstructGPT changed the focus completely. For the first time, large-scale AI development began shifting from model-centric AI to interaction-centric AI.

This was a major philosophical transition: the industry realized that users didn't only care about raw intelligence, benchmark scores, or parameter counts.

They cared about usability, conversational quality, safety, trust, and whether the system could actually help them effectively.

This is why ChatGPT felt so different to the public. The underlying language model capabilities were important, but the real breakthrough came from how those capabilities were shaped into a usable human experience.

The interface became conversational. The system became more cooperative. The AI became more aligned with user intent.

That shift fundamentally changed public perception of artificial intelligence.

Before ChatGPT, most people saw AI as research software, technical demos, or specialized tools for experts.

After ChatGPT, millions of people started interacting with AI systems conversationally on a daily basis.

And that changed everything.

Earlier GPT papers focused mainly on discovering what scaling could achieve. InstructGPT introduced a different challenge: How do we safely deploy these systems in the real world?

That shift helped create entirely new areas of research and engineering, including RLHF pipelines, safety tuning, refusal behavior, red teaming, adversarial testing, policy frameworks, and large-scale human-feedback infrastructure.

In many ways, the ChatGPT era began the moment researchers realized that building powerful models was only part of the problem.

The harder challenge was making those systems reliable enough for human interaction at global scale.

It also helps explain why later systems placed much greater emphasis on safety, alignment, deployment practices, and real-world reliability.

The industry was no longer building language models only for research papers. It was building AI systems intended to operate in the real world. And the InstructGPT paper became one of the clearest turning points in that transformation.

Discussion: The Real Shift

The transition from GPT-3 to ChatGPT represents something much deeper than a simple improvement in model performance.

It changed the central question driving the entire AI industry.

During the GPT-3 era, the big question was, “Can language models learn tasks directly from prompts?”

That was the breakthrough introduced by GPT-3.

Research attention shifted toward scaling and emergent capabilities.

But the ChatGPT era introduced a completely different challenge: the question was no longer simply “Can the model perform the task?” Instead, it became, “Can humans actually trust and use these systems every day?”

That shift changed everything.

Once millions of people began interacting with AI systems directly, raw intelligence alone was no longer sufficient. Users needed systems that were understandable, reliable, safe, conversational, and aligned with human expectations.

This is exactly why the InstructGPT paper became so historically important. It introduced the idea that large language models should not only optimize for capability, but also for human interaction quality.

In many ways, the industry moved from “How smart is the model?” to “How usable is the model?”

And that transition fundamentally changed AI development.

After ChatGPT, success was no longer measured only by benchmark scores, parameter counts, or scaling curves.

It was increasingly measured by alignment, conversational quality, safety, and real-world usability.

This also explains why alignment research suddenly became central to modern AI systems.

GPT-3 showed that models could learn from prompts. ChatGPT showed that humans needed models that could cooperate.

That was the real shift.

And it may ultimately become one of the most important turning points in the history of artificial intelligence.

Connection to GPT-4

One of the most important things to understand about GPT-4 is that it didn't appear out of nowhere.

It was built on top of the alignment ideas introduced by InstructGPT and refined through the large-scale deployment experience of ChatGPT.

GPT-4 is often discussed in terms of its reasoning, multimodal abilities, and benchmark performance.

But beneath all of those improvements is something equally important: the alignment pipeline.

Without the work introduced in the InstructGPT paper, GPT-4 would likely feel far less usable as a real-world assistant.

That distinction matters enormously.

Many of GPT-4's alignment techniques can be traced back to ideas introduced by InstructGPT, including RLHF, instruction tuning, conversational alignment, safer refusal behavior, and human preference optimization.

ChatGPT then became the large-scale real-world testing ground for these ideas.

Millions of user interactions exposed weaknesses ranging from hallucinations and jailbreak attempts to broader safety and usability issues.

Those deployment lessons became incredibly valuable.

By the time GPT-4 arrived, OpenAI was no longer simply training a larger language model. It was building a large-scale aligned conversational system shaped by RLHF pipelines, human feedback, safety engineering, adversarial testing, and real-world user interaction.

This is why GPT-4 feels fundamentally different from earlier GPT models.

In many ways, GPT-4 represents the convergence of two major ideas: scaling capability and scaling alignment.

• GPT-3 proved that language models could learn tasks from prompts.

• InstructGPT proved that models could be shaped through human feedback.

• ChatGPT proved that aligned conversational AI could work at global scale.

• GPT-4 combined all of those ideas into a much more capable multimodal system.

That historical progression is important because it shows that modern AI systems aren't built through scaling alone. They're built through the combination of intelligence, alignment, interaction design, and deployment experience.

And the InstructGPT paper became one of the key foundations that made GPT-4 possible.

GPT-3 vs InstructGPT vs ChatGPT vs GPT-4: Key Differences

By this point, we've discussed GPT-3, InstructGPT, ChatGPT, and GPT-4 individually. But it can be helpful to see them side by side.

Although these systems are closely related, each one introduced a different shift in the evolution of modern AI.

GPT-3 focused on capability through scale, InstructGPT focused on alignment through human feedback, ChatGPT focused on conversational usability, and GPT-4 combined these ideas with stronger reasoning and multimodal capabilities.

The table below summarizes the main differences between them and shows how each system built on the progress of the previous generation.

From GPT-1 to GPT-4: A Timeline of Modern AI Systems and Alignment Evolution

Before we wrap up, it's worth stepping back and looking at the bigger picture.

The InstructGPT paper didn't emerge in isolation. It was part of a much larger evolution that transformed GPT models from research-focused language models into the conversational AI systems we use today.

Each generation introduced a new idea that pushed the field forward.

GPT-1 introduced large-scale pretraining, GPT-2 demonstrated zero-shot capabilities, GPT-3 popularized prompting and in-context learning, and InstructGPT introduced alignment through human feedback. ChatGPT then brought these ideas to millions of users through a conversational interface, while GPT-4 combined alignment with stronger reasoning and multimodal capabilities.

The timeline below summarizes the key transitions that shaped the modern AI era.

Final Insight

When people look back at the history of modern AI, they often focus on the moments when models became larger, more powerful, or more capable. But the story of the GPT series is not just a story about scale. It is also a story about learning how to make that intelligence useful.

GPT-1 showed that language models could learn surprisingly rich representations from large amounts of text before being adapted to specific tasks.

GPT-2 expanded that idea and revealed that scale itself could unlock new behaviors.

GPT-3 pushed the field into entirely new territory, demonstrating that a single model could perform a wide variety of tasks simply by responding to prompts and examples.

For a moment, it seemed as though scaling might be the answer to everything.

Then InstructGPT arrived and exposed a different challenge.

The problem was no longer whether a model could generate text, answer questions, or complete tasks. Models were already becoming remarkably capable.

The real question was whether people could actually rely on them. Could they follow instructions consistently? Could they respond in ways users found helpful? Could they become something more than sophisticated prediction engines?

That was the breakthrough at the heart of InstructGPT.

Rather than focusing solely on making models smarter, the paper focused on making them behave better.

Human feedback became part of the training process itself.

Alignment moved from a research concern to a core design principle. For the first time, improving the relationship between humans and AI became just as important as improving the model's raw capabilities.

The impact of that shift extended far beyond a single paper.

It laid the groundwork for ChatGPT, which introduced millions of people to conversational AI. Suddenly, interacting with advanced language models no longer required APIs, research expertise, or carefully engineered prompts. People could simply ask questions, seek advice, explore ideas, or learn something new through natural conversation.

That change transformed AI from a research breakthrough into a widely used product.

GPT-4 would later build on this foundation, combining stronger reasoning and broader capabilities with the alignment techniques that began with InstructGPT. But by then, the industry had already learned an important lesson: capability alone was not enough. Intelligence had to be usable.

In hindsight, the lasting significance of the InstructGPT paper is not that it introduced a new training pipeline. It is that it helped redefine the goal of modern AI.

The challenge was no longer just building systems that could generate language.

It was building systems that people could work with, learn from, and trust.

And that may ultimately be the transition that defined this era of artificial intelligence.

Resources:

• Pytorch Projects for GPT series

• Training Language Models to Follow Instructions with Human Feedback

• Language Models are Few-Shot Learners

• Learning to Summarize from Human Feedback

• Fine-Tuning Language Models from Human Preferences

• Deep Reinforcement Learning from Human Preferences

• Learning to Summarize with Human Feedback

• Aligning AI With Shared Human Values

• Asking for Help on Recursive Decomposition

• WebGPT: Browser-assisted Question-Answering with Human Feedback

• Constitutional AI: Harmlessness from AI Feedback

• TruthfulQA: Measuring How Models Mimic Human Falsehoods

• RealToxicityPrompts: Evaluating Neural Toxic Degeneration in Language Models

• The Power of Scale for Parameter-Efficient Prompt Tuning

• Finetuned Language Models Are Zero-Shot Learners

• Multitask Prompted Training Enables Zero-Shot Task Generalization

Contact Me

• Github

• X

• Linkedin

Most flagship devices back then shipped with somewhere between 2 and 8 GB of RAM, and GPUs were nowhere near what we carry around today. My mom’s Galaxy Note 3 featured the Qualcomm Adreno 330 GPU with 32 unified shader cores running at up to 578 MHz — a complete powerhouse for its time.

Fast forward to today, and the phones in our pockets are ridiculously more powerful, more efficient, and, honestly, capable of things people would’ve considered science fiction back then.

But enough about my mom’s phone. What I’m really trying to say is this: instead of spending hundreds of dollars every month on AI subscriptions and tokens, we can take advantage of the insanely capable devices we already carry around every day.

Modern smartphones now have dedicated AI acceleration, impressive thermal efficiency, and enough compute power to run lightweight language models locally, completely offline. That means better privacy, full control over your chat history, lower latency, and the ability to use AI without depending entirely on cloud services.

In this article, we’re going to build a React Native application that interacts with an LLM running directly on the device itself. The implementation will revolve around QVAC, a family of inference tools designed specifically for running AI models locally.

Table of Contents

• Prerequisites

• What is QVAC?

• Environment Setup

• Model Management

• Custom Models

• Complete Implementation

• Codebase Breakdown

• Conclusion

• Resources & Further Reading

Prerequisites

To get the most out of this article, you should have a basic understanding of front end development and React in general. You don't have to be a mobile developer, but understanding React will help a lot.

What is QVAC?

QVAC (QuantumVerse Automatic Computer) is a local-first AI inference platform developed by Tether. It's designed to move artificial intelligence away from centralized cloud systems and bring computation back to the user’s own device.

Most modern AI tools rely heavily on remote servers, API keys, and cloud infrastructure controlled by a handful of companies. While this makes AI accessible, it also creates major concerns around privacy, censorship, vendor lock-in, internet dependency, and ownership of user data. Every prompt, conversation, or uploaded file often passes through third-party servers that users have little control over.

QVAC was designed to solve that problem by allowing AI models and agents to run directly on devices like smartphones, laptops, and embedded systems, even while completely offline. Instead of sending personal conversations and sensitive data to the cloud, users can process everything locally on their own hardware.

The platform also embraces decentralization through peer-to-peer communication, reducing reliance on centralized infrastructure and eliminating single points of failure. This approach makes AI systems more private, resilient, autonomous, and accessible, especially in environments with limited internet access or strict data privacy requirements.

In simple terms, QVAC exists to make AI truly owned by its users — local-first, private by default, and independent from centralized control.

Environment Setup

To speed up the process, I prepared a React Native starter project with all the dependencies installed. But we will install and set up QVAC in this article, since that's our main topic. Here's a link to the repository.

Or you can run the below command to clone the starter project.

git clone --branch ft-ui-implementation --single-branch https://github.com/DjibrilM/QVAC-offline-Chatbot-Article-Project-

QVAC Installation

Run the following command to install the SDK: npm i @qvac/sdk. Feel free to use any package manager of your choice. As for me, I will keep things simple with npm.

Then add the following peer dependencies to your package.json:

{
  "dependencies": {
    "@qvac/sdk": "^0.7.0",
+   "bare-rpc": "^1.0.0", 
    "expo": "~54.0.33",
    "expo-status-bar": "~3.0.9",
    "react": "19.1.0",
    "react-native": "0.81.5",
+   "react-native-bare-kit": "^0.11.5"  
  },
  "devDependencies": {
    "@types/react": "~19.1.0",
    "bare-pack": "^1.5.1", 
    "typescript": "~5.9.2"
  }
}

Install the following additional dependencies:

npx expo install expo-file-system expo-build-properties expo-device

Then configure expo-build-properties and add @qvac/sdk/expo-plugin to the plugins array in your app.json:

{
  "expo": {
    "plugins": [
      "expo-router",
      "@qvac/sdk/expo-plugin",
      [
        "expo-splash-screen",
        {
          "backgroundColor": "#208AEF",
          "android": {
            "image": "./assets/images/splash-icon.png",
            "imageWidth": 76
          }
        }
      ]
    ]
  }
}

Run the following command to build the native modules:

npx expo prebuild

Note: QVAC uses llama.cpp under the hood. Due to optimization requirements and native hardware dependencies, the QVAC SDK doesn't run on emulators. You'll have to test this with a real physical device with Developer Mode enabled.

To run the app on your physical device, execute:

# For Android:
npx expo run:android --device

# For iOS:
npx expo run:ios --device

Model Management

The QVAC model management system is completely local-first and decentralized. It handles the entire lifecycle, from downloading files to lifecycle optimization, abstracting everything behind clean utility APIs.

Resumable & Deduplicated Downloading (downloadAsset)

It writes temporary chunks to local disk. If a network drop occurs, the partial file is preserved and resumes automatically upon the next call. Also, if multiple components invoke a download for the same asset simultaneously, QVAC handles the streaming under a single network stream.

Memory Lifecycle (loadModel & unloadModel)

loadModel maps the asset file directly into memory, maps it to your hardware target (such as the device GPU), and exposes an ephemeral modelId. Because local inference is highly memory-intensive on mobile devices, calling unloadModel frees system RAM immediately while preserving the downloaded file on disk.

Custom Models

Because QVAC relies on an optimized branch of llama.cpp, it remains highly compatible with the open-source AI ecosystem. If you plan to load custom models, ensure they adhere to these criteria:

• Format: Must be in the GGUF (.gguf) format.

• Quantization: For mobile and edge deployments, always prioritize Q4_0, Q4_K_M, or Q8_0 configurations to guarantee they fit safely within mobile hardware RAM constraints.

Complete Implementation

Now let's replace your main file codebase logic with the full implementation, combining the UI container layout, user interaction state, model lifecycle setup, and real-time inference handling into a cohesive structure.

Replace your entry file with the following code:

import { ChatInput } from "@/components/chat-input";
import { ChatMessage, Message } from "@/components/chat-message";
import { ModelLoader } from "@/components/model-loader";
import { Button } from "@/components/ui/button";
import { Text } from "@/components/ui/text";

import {
  completion,
  deleteCache,
  downloadAsset,
  LLAMA_3_2_1B_INST_Q4_0,
  loadModel,
  type ModelProgressUpdate,
  VERBOSITY,
} from "@qvac/sdk";
import { SymbolView } from "expo-symbols";
import { useEffect, useRef, useState } from "react";

import {
  Clipboard,
  KeyboardAvoidingView,
  Platform,
  SafeAreaView,
  ScrollView,
  View,
} from "react-native";

const makeId = () => Math.random().toString(36).substring(2, 9);

export default function Index() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [input, setInput] = useState("");
  const [isGenerating, setIsGenerating] = useState(false);

  // Model loading state
  const [modelId, setModelId] = useState<string | null>(null);
  const [isModelLoaded, setIsModelLoaded] = useState(false);
  const [isDownloading, setIsDownloading] = useState(false);
  const [downloadProgress, setDownloadProgress] = useState(0);

  const scrollViewRef = useRef<ScrollView>(null);
  const messagesRef = useRef<Message[]>([]);

  useEffect(() => {
    messagesRef.current = messages;
  }, [messages]);

  const startDownload = () => {
    setIsDownloading(true);
    setupModel();
  };

  // Automatically scroll to bottom when messages list updates
  useEffect(() => {
    if (scrollViewRef.current) {
      setTimeout(() => {
        scrollViewRef.current?.scrollToEnd({ animated: true });
      }, 100);
    }
  }, [messages, isGenerating]);

  const copyToClipboard = (text: string) => {
    if (Platform.OS === "web") {
      navigator.clipboard.writeText(text);
    } else {
      Clipboard.setString(text);
    }
  };

  const setupModel = async () => {
    try {
      setIsDownloading(true);
      setDownloadProgress(0);
      
      // 1. Local download path execution
      await downloadAsset({
        assetSrc: LLAMA_3_2_1B_INST_Q4_0,
        onProgress: (progress: ModelProgressUpdate) => {
          setDownloadProgress(progress.percentage / 100);
        },
      });

      setDownloadProgress(1);

      // 2. Load model into runtime memory
      const loadedModel = await loadModel({
        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
        modelType: "llm",
        modelConfig: {
          device: "gpu",
          ctx_size: 2048,
          verbosity: VERBOSITY.ERROR,
        },
      });

      setModelId(loadedModel);
      setIsModelLoaded(true);
      setIsDownloading(false);
    } catch (e: any) {
      console.error("Error setting up model:", e);
      setIsDownloading(false);
    }
  };

  async function handleSend() {
    // Guard against sending before the model is ready or while generating.
    if (!modelId || isGenerating) return;

    const trimmed = input.trim();
    if (!trimmed) return;

    setInput("");
    setIsGenerating(true);

    // Append user message and a placeholder assistant message for streaming.
    const userMsg: Message = {
      id: makeId(),
      role: "user",
      content: trimmed,
    };

    const assistantId = makeId();

    const assistantMsg: Message = {
      id: assistantId,
      role: "assistant",
      content: "",
    };

    setMessages((prev) => [...prev, userMsg, assistantMsg]);

    try {
      // Build chat history for the completion request.
      const history = [...messagesRef.current, userMsg].map((m) => ({
        role: m.role,
        content: m.content,
      }));

      // Run a streaming completion and update the last assistant bubble.
      const result = completion({
        modelId,
        history,
        stream: true,
      });

      let acc = "";

      for await (const token of result.tokenStream) {
        acc += token;

        // Update only the last assistant message content
        setMessages((prev) =>
          prev.map((m) =>
            m.id === assistantId ? { ...m, content: acc } : m
          )
        );
      }

      // Optional: Log completion performance stats
      try {
        const stats = await result.stats;
        console.log("📊 Completion stats:", stats);
      } catch {}

    } catch (e: any) {
      // Show any error in the assistant bubble.
      setMessages((prev) =>
        prev.map((m) =>
          m.id === assistantId
            ? { ...m, content: `❌ Error: ${e?.message ?? String(e)}` }
            : m
        )
      );
    } finally {
      setIsGenerating(false);
    }
  }

  if (!isModelLoaded) {
    return (
      <ModelLoader
        onDownload={startDownload}
        isDownloading={isDownloading}
        progress={downloadProgress}
      />
    );
  }

  return (
    <SafeAreaView className="flex-1 bg-background">
      <KeyboardAvoidingView
        behavior={Platform.OS === "ios" ? "padding" : "height"}
        className="flex-1"
      >
        <View className="flex-row items-center justify-between p-4 border-b border-border">
          <View className="flex-row items-center gap-2">
            <View className="w-2 h-2 rounded-full bg-emerald-500" />
            <Text className="font-semibold text-lg">Local Llama 3.2</Text>
          </View>
          <Text className="text-xs text-muted-foreground">Offline Engine</Text>
        </View>

        <ScrollView
          ref={scrollViewRef}
          className="flex-1 px-4"
          contentContainerStyle={{ paddingVertical: 16, gap: 16 }}
        >
          {messages.filter(m => m.content !== "" || m.role === "assistant").map((msg) => (
            <ChatMessage
              key={msg.id}
              message={msg}
              onCopy={() => copyToClipboard(msg.content)}
            />
          ))}
        </ScrollView>

        <ChatInput
          value={input}
          onChangeText={setInput}
          onSend={handleSend}
          disabled={isGenerating}
          placeholder={isGenerating ? "Thinking..." : "Type a message..."}
        />
      </KeyboardAvoidingView>
    </SafeAreaView>
  );
}

Codebase Breakdown

Let’s lift the hood on how this unified component manages local model workflows and real-time UI streaming.

1. Tracking Model State & Asynchronous Synchronization

At the root of the component, we track both user-facing interface state and underlying QVAC runtime handles:

const [messages, setMessages] = useState<Message[]>([]);
const [modelId, setModelId] = useState<string | null>(null);
const [isModelLoaded, setIsModelLoaded] = useState(false);
const [isDownloading, setIsDownloading] = useState(false);
const [downloadProgress, setDownloadProgress] = useState(0);

Because state setters in React are asynchronous, streaming loops can accidentally capture stale representations of current chat logs.

To circumvent this, a mutable messagesRef acts as a real-time single source of truth for the active session state:

const messagesRef = useRef<Message[]>([]);

useEffect(() => {
  messagesRef.current = messages;
}, [messages]);

2. Orchestrating Download & Memory Instantiation

When the user strikes the download button action trigger, the application launches setupModel(). This function splits tasks clearly across local storage caching and active hardware allocation layers:

await downloadAsset({
  assetSrc: LLAMA_3_2_1B_INST_Q4_0,
  onProgress: (progress: ModelProgressUpdate) => {
    setDownloadProgress(progress.percentage / 100);
  },
});

• Storage Sync: downloadAsset reaches out to pull the designated standard model signature down into mobile device disk files.

• Hardware Binding: Once safe on disk, loadModel executes to wake up the engine runtime:

const loadedModel = await loadModel({
  modelSrc: LLAMA_3_2_1B_INST_Q4_0,
  modelType: "llm",
  modelConfig: {
    device: "gpu",
    ctx_size: 2048,
    verbosity: VERBOSITY.ERROR,
  },
});

Passing device: "gpu" tells QVAC to run hardware-accelerated kernels across the smartphone's graphic processing hardware structure, ensuring rapid performance metrics instead of locking execution to slower CPU loops.

3. Pipeline Ingest & Streaming Generation Loop

Once user validation confirms the prompt is ready, handleSend() sets up user bubbles and generates an empty assistant placeholder card to catch token output segments.

The application map transforms references straight out of messagesRef.current into a structured history syntax before processing:

const result = completion({
  modelId,
  history,
  stream: true,
});

With stream: true enabled, QVAC doesn't hold up your application thread waiting for long string sequences to complete. Instead, it yields an asynchronous iterable stream that spits out fresh updates instantly:

let acc = "";

for await (const token of result.tokenStream) {
  acc += token;

  setMessages((prev) =>
    prev.map((m) =>
      m.id === assistantId ? { ...m, content: acc } : m
    )
  );
}

The loop continuously concatenates token text variables into the tracking accumulator (acc), target patching state properties exclusively against our placeholder identifier (assistantId). This creates a lightning-fast typing animation experience while executing fully offline on your user's physical device hardware.

Conclusion

Building a local-first AI application is no longer a concept confined to high-end desktops or specialized research labs. As we’ve seen, the smartphones we carry in our pockets every day possess more than enough computational muscle and dedicated hardware acceleration to run highly capable language models completely offline.

By leveraging React Native and the QVAC SDK, we successfully bypassed the traditional cloud-dependent architecture. We eliminated the need for complex server infrastructure, API key management, and recurring token subscription fees, all while providing an ultra-private, low-latency, streaming chat experience directly on-device.

As open-source models continue to shrink in size and grow in capabilities, edge inference will become an essential architecture for developers prioritizing privacy, offline resilience, and cost efficiency. The power to compute is back where it belongs: in the hands of the user.

Resources & Further Reading

To dive deeper into local inference, inspect the source code, or explore advanced configurations for your mobile applications, check out the following resources:

• QVAC Expo Integration Tutorial – The official step-by-step documentation for configuring QVAC within the Expo and React Native ecosystems.

• Project GitHub Repository – Access the complete source code, including the UI layout components, starter themes, and full configuration files used in this guide.

• Llama.cpp Official Repository – Learn more about the underlying inference engine that powers QVAC's hardware-accelerated local execution.

• Hugging Face GGUF Models – Explore thousands of open-source, quantized models that you can download and experiment with inside your local application.

But JavaScript has an interesting limitation that many developers don't fully understand until it causes a production issue. That limitation is called the safe integer limit.

In this article, you'll learn:

• What the safe integer limit is

• Why JavaScript has this limitation

• How precision errors happen

• What BigInt is

• How modern systems use BigInt

• How to use large integers safely in production applications

Table of Contents

• Prerequisites

• What Is the Safe Integer Limit in JavaScript?

• Why Is It Called a “Safe” Integer?

• How Can You Understand This Problem if You Are New to the Game?

• How to Check if a Number Is Safe

• Can Unsafe Integers Cause Any Problems?

• Introducing BigInt in JavaScript

  • How to Perform Operations with BigInt

  • How BigInt Differs from Number

  • How Modern Software Uses BigInt

  • When You Should Use BigInt

  • When You Should Not Use BigInt

• Final Thoughts

Prerequisites

To follow along with this article, you should have:

• Basic knowledge of JavaScript

• A code editor or browser console

• Familiarity with variables and functions

What Is the Safe Integer Limit in JavaScript?

JavaScript uses the Number type to represent numbers.

For example:

const age = 25
const price = 99.99
const count = 1000

Under the hood, JavaScript stores numbers using the IEEE 754 double-precision floating-point format. You don't need to memorize the entire specification, but you should understand one important consequence: JavaScript can only represent integers accurately up to a certain point.

That point is:

console.log(Number.MAX_SAFE_INTEGER) // 9007199254740991

This is the largest integer JavaScript can safely represent using the Number type.

The smallest safe integer is:

console.log(Number.MIN_SAFE_INTEGER) // -9007199254740991

Why Is It Called a “Safe” Integer?

The word “safe” means JavaScript can still represent the integer accurately without losing precision. Once you go beyond the safe limit, JavaScript starts making approximation mistakes.

Let’s look at an example.

const max = Number.MAX_SAFE_INTEGER

console.log(max + 1) // 9007199254740992
console.log(max + 2) // 9007199254740992

This is incorrect because adding 1 and 2 shouldn't produce the same result, but guess what? This happens because JavaScript can no longer distinguish between nearby large integers accurately.

How Can You Understand This Problem if You Are New to the Game?

Imagine you have a camera. When you zoom in closely, you can see every small detail clearly. But when you zoom out too far, tiny details begin to disappear.

JavaScript numbers behave similarly. Small integers are represented precisely:

console.log(10)
console.log(100)
console.log(1000)

But extremely large integers lose detail because JavaScript runs out of precision. At that point, multiple numbers begin collapsing into the same value internally. That is why large integer calculations become unreliable.

How to Check if a Number Is Safe

JavaScript provides a built-in method called Number.isSafeInteger().

Example:

console.log(Number.isSafeInteger(100)) // true

Another example:

console.log(Number.isSafeInteger(Number.MAX_SAFE_INTEGER)) // true

But the below code returns false:

console.log(
  Number.isSafeInteger(Number.MAX_SAFE_INTEGER + 1)
) // false

This method is useful when validating large integers from APIs, databases, or user input.

Can Unsafe Integers Cause Any Problems?

Unsafe integers can create serious production bugs. For example, in financial calculations: imagine a payment platform processing extremely large transaction records. Precision issues can corrupt balances or reconciliation logic.

const amount = 9007199254740993

console.log(amount) // 9007199254740992

The value changes unexpectedly. That's dangerous for financial systems.

Another example is in analytics systems. Large-scale analytics platforms often track billions or trillions of events. Unsafe integers can distort counters and reports.

Also, distributed systems frequently generate very large IDs. Examples include database IDs, event IDs, transaction IDs, and blockchain transaction hashes. If precision is lost, systems may reference the wrong records.

Blockchain systems also commonly use extremely large integers. Ethereum, for example, stores values in wei. One Ether equals:

1,000,000,000,000,000,000 wei

That number exceeds JavaScript’s safe integer limit. Without proper handling, balances become inaccurate.

Introducing BigInt in JavaScript

JavaScript introduced BigInt to solve this problem. BigInt allows JavaScript to represent integers larger than the safe limit accurately. You can create a BigInt by adding n to the end of a number.

Example:

const largeNumber = 9007199254740993n

console.log(largeNumber) // 9007199254740993n

Notice that the value remains accurate. You can also create BigInt values using the BigInt() constructor.

const value = BigInt("9007199254740993123123123")

console.log(value)

How to Perform Operations with BigInt

You can use arithmetic operators with BigInt.

Here's an example:

const a = 1000000000000000000n
const b = 2n

console.log(a + b) // 1000000000000000002n
console.log(a - b) // 999999999999999998n
console.log(a * b) // 2000000000000000000n
console.log(a / b) // 500000000000000000n

How BigInt Differs from Number

One important rule is that you can't mix BigInt and Number directly.

This will throw an error:

const result = 1n + 1 // TypeError

You must convert explicitly, like this:

const result = 1n + BigInt(1)

console.log(result)

Or this:

const result = Number(1n) + 1

console.log(result)

Explicit conversion prevents accidental precision loss.

How Modern Software Uses BigInt

Many modern applications rely on BigInt. Let’s look at a practical example. Blockchain applications depend heavily on precise integer calculations.

Example:

const wei = 1000000000000000000n
const balance = 5000000000000000000n

console.log(balance / wei) // 5n

Libraries in Ethereum ecosystems often use BigInt internally for token balances and gas calculations.

When You Should Use BigInt

Use BigInt when:

• Integer precision matters

• Numbers exceed the safe limit

• You're building blockchain applications

• You're handling financial ledgers

• You're processing massive counters

• You're working with large database IDs

When You Should Not Use BigInt

Avoid BigInt when:

• You need decimal calculations

• You're building simple frontend interactions

• Precision isn't critical

• Performance matters more than huge integer support

BigInt operations are slower than normal Number operations because they require arbitrary-precision arithmetic.

Final Thoughts

JavaScript’s safe integer limit isn't just a theoretical concept. It affects real-world systems every day. As applications grow larger and more distributed, developers increasingly work with massive integers in payment systems, blockchain platforms, analytics pipelines, databases, event-driven architectures, and so on.

Understanding the safe integer limit helps you avoid subtle production bugs that are often difficult to detect. BigInt gives JavaScript the ability to handle these large integers safely and accurately. But like any powerful tool, it should be used intentionally.

Just keep in mind: Use normal Number values for everyday calculations. Use BigInt when precision becomes critical.

The key lesson is simple: large numbers aren't always safe numbers in JavaScript.

Kubernetes can seem intimidating at first, but Amazon EKS (Elastic Kubernetes Service) makes it much more approachable, especially when you have a step-by-step guide to follow.

In this tutorial, we'll walk through exactly how to get a Spring Boot application with a MySQL database up and running on Amazon EKS. I'll take you from from containerizing your app to connecting it to a managed database, all the way to accessing it live in the cloud. Let’s get started.

Table of Contents

• Prerequisites

• Application Overview

• What is Amazon EKS?

• How to Deploy a Spring Boot App with MySQL on Amazon EKS

  • Step 1: Create the VPC

  • Step 2: Set Up the MySQL Database in a Private Subnet

  • Step 3: Deploy EC2 Instance in a Public Subnet

  • Step 4: Create SSH Tunneling for the Database

  • Step 5: Set Up a Simple SpringBoot Application Development

  • Step 6: Configure SpringBoot App for Database

  • Step 7: Dockerize the Spring Boot Application

  • Step 8: Push the Image to Elastic Container Registry (ECR)

  • Step 9: Implement AWS App Load Balancer

  • Step 10: Create a Cluster in EKS

  • Step 11: Install AWS Load Balancing

  • Step 12: Create and Deploy Kubernetes

  • Step 13: Delete Cluster

• Conclusion

Prerequisites

Before you begin, ensure you have the following:

• Basic knowledge of AWS (AWS Console access).

• Basic knowledge of containerization.

• Working knowledge of Kubernetes.

• Basic knowledge of databases.

• Helm installed

• Kubectl installed

• Eksctl installed

• An IDE

Application Overview

The application runs inside an AWS VPC spread across two availability zones for high availability. When a user makes a request, it flows through an Internet Gateway into an AWS Application Load Balancer sitting in the public subnet, which handles incoming traffic via an Ingress rule.

The Load Balancer routes requests to the App Service, which distributes them across multiple App Pods running inside AWS EKS (Elastic Kubernetes Service) in the private subnets.

The Docker images for these pods are pulled from AWS ECR (Elastic Container Registry). For data persistence, the app pods connect to Amazon RDS MySQL databases through a MySQL External Service, with an RDS instance in each availability zone to ensure redundancy.

A NAT Gateway in the public subnet allows the private resources to make outbound internet calls without being directly exposed to the internet.

What is Amazon EKS?

If you've ever tried to manage containers manually, you already know it can get messy pretty quickly, tracking which containers are running, restarting ones that crash, scaling up when traffic spikes... It's a lot.

That's exactly the problem Kubernetes was built to solve. It automates the deployment, scaling, and management of containerized applications. But setting up and maintaining your own Kubernetes cluster from scratch? That's a whole other challenge.

That's where Amazon EKS comes in. EKS is a fully managed Kubernetes service provided by AWS, which means AWS handles the heavy lifting of setting up, securing, and maintaining the Kubernetes control plane for you. You just focus on deploying your application.

How to Deploy a Spring Boot App with MySQL on Amazon EKS

In this section, we’ll cover the steps to follow in deploying your SpringBoot application with MySQL on Amazon EKS.

Step 1: Create the VPC

To create a VPC, log in to the AWS IAM Console and search for “VPC,” then click create VPC.

Select the "VPC and more option:, and give your VPC a name for your project, for example, spring-demo. Set the IPv4 CIDR block to 10.4.0.0/16. For the NAT gateway configuration, select Zonal, then In 1 AZ.

Select None for VPC endpoints configuration. Next, click Create VPC, then click View VPC. This takes you to the VPC resource map.

Step 2: Set Up the MySQL Database in a Private Subnet

First, you need to create the security group for the MySQL and EC2 instance deployment. To do that, navigate to EC2 > Security Groups. For the inbound rule, select Type: All traffic and Source: Anywhere-IPv4. Then click Create security group.

Next, we’ll create the subnet group for the database. To do that, navigate to Aurora and RDS > Subnet groups and click Create DB subnet group. Next, configure the DB subnet to include:

• Name: private-subnet-db

• Description: private-subnet-db

• VPC: Select VPC

• Add subnets: Choose us-east-1a and us-east-1b as the availability zones, then select the private and public subnets

Click Create**.**

Now, navigate to Databases, click Create database, and select Full configuration. Select MySQL as the engine type.

Select the Free tier when choosing a sample template. Next, give your DB a username and a strong password. Choose db.t3.micro as the instance type.

Select your VPC and associated private subnet. Now, uncheck the "Enable auto minor version upgrade" option in the Additional configuration section and click Create database.

While our database initializes, let's create a key pair for the EC2 instance, which will be launched in a public subnet. To do that, navigate to EC2 > Network & Security > Key Pairs and click Create key pair.

Give your key pair a name, for example, ece-db-key-pair. Leave everything else as-is and click Create key pair. This automatically downloads the key-pair into your local machine.

Step 3: Deploy EC2 Instance in a Public Subnet

Now it’s time to create an EC2 instance. To do this, navigate to EC2 > Instances and click Launch instances. Select the key pair you just created in the Key pair section.

Next, in the Network section, select the VPC created earlier for the project. For Auto-assign public IP, choose Enable. Next, choose the Select existing security group option and select the all-access-sg security group created earlier. Next, click Launch instance.

Step 4: Create SSH Tunneling for the Database

For this step, go into your terminal and navigate to the folder where your key pair is downloaded. Run the ls command, and you should see your key pair there.

Next, you need to change the permission of the key pair file. Use the command below:

chmod 0400 ece-db-key-pair.pem 

Now, run the SSH tunneling command below:

ssh -i <YOUR-KEY-PAIR>.pem -f -N -L <LOCAL-PORT>:<YOUR-RDS-ENDPOINT>:<RDS-PORT> <EC2-USERNAME>@<YOUR-EC2-PUBLIC-DNS> -v

• <YOUR-KEY-PAIR>.pem: the name of your downloaded key pair file

• <LOCAL-PORT>:  the port on your laptop (3306 for MySQL, 5432 for PostgreSQL)

• <YOUR-RDS-ENDPOINT>: found in AWS Console > RDS > Your database > Connectivity & Security > Endpoint

• <RDS-PORT>: same as local port (3306 for MySQL, 5432 for PostgreSQL)

• <EC2-USERNAME>: usually ec2-user for Amazon Linux, ubuntu for Ubuntu

• <YOUR-EC2-PUBLIC-DNS>: found in AWS Console > EC2 > Your instance > Public IPv4 DNS

This command lets your laptop or local machine talk directly to your remote database, as if the database were sitting on your own computer.

After running this command, you can open a database tool (like MySQL Workbench, DBeaver, or TablePlus) on your laptop and connect to:

• Host: localhost

• Port: 3306

For this tutorial, I’ll be using the community version of DBeaver. You can use other similar tools, but if you prefer to use the same tool for the purpose of this guide, you can install the community version from the official DBeaver download page.

After download and installation, open the DBeaver client and click the Connect to a database icon in the top-left corner of the app.

Select MySQL and click Next. On the next window, enter your database username and password, and set Server Host to 127.0.0.1.

Click Test Connection.

You should see a window appear on your screen, indicating that the connection is successful.

Click OK and Finish.

Now, on the left panel, you should see your connection. Expand it to see the database structure.

Now, you have successfully created SSH tunneling for your database.

Troubleshooting

While attempting to test the database connection, I initially ran into a “Plugin 'mysql_native_password' is not loaded” error. If you encounter this error, follow the steps below to fix it.

1. On the Connection Settings window, navigate to the Driver properties tab.

2. Look for allowPublicKeyRetrieval and set it to FALSE.

3. Navigate back to the Main tab and click Test Connection.

Everything should work fine now.

Step 5: Set Up a Simple SpringBoot Application Development

To get started, head over to the Spring Initializr website. Rename Artifact to “springboot-mysql-eks”. Then click ADD DEPENDENCIES… to add dependencies for the REST APIs. Search for the following dependencies:

• Spring Web: Build web apps, including RESTful applications using Spring MVC. Uses Apache Tomcat as the default embedded container.

• Spring Data JPA: Persist data in SQL stores with the Java Persistence API using Spring Data and Hibernate.

• IBM DB2 Driver: A JDBC driver that provides access to IBM DB2.

• Lombok: A Java annotation library that helps to reduce boilerplate code.

Next, click GENERATE at the bottom center of the page. This action downloads a zip file to your local machine. Open this file in an IDE, such as VSCode or IntelliJ IDEA. For this tutorial, I use VSCode. In the build.gradle file, you can see all the added dependencies:

dependencies {
   implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
   implementation 'org.springframework.boot:spring-boot-starter-webmvc'
   compileOnly 'org.projectlombok:lombok'
   runtimeOnly 'com.ibm.db2:jcc'
   annotationProcessor 'org.projectlombok:lombok'
   testImplementation 'org.springframework.boot:spring-boot-starter-data-jpa-test'
   testImplementation 'org.springframework.boot:spring-boot-starter-webmvc-test'
   testCompileOnly 'org.projectlombok:lombok'
   testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
   testAnnotationProcessor 'org.projectlombok:lombok'
}

What we're building

The Spring Boot app is a currency exchange rate and conversion app:

We'll be inserting the exchange data into the database table.

To continue with this tutorial, you can clone the project repo here to save time.

In main > java > com.. > model > ExchangeRate, you’ll see the code below:

package com.example.springbootmysqleks.model;

import jakarta.persistence.*;
import lombok.Getter;
import lombok.Setter;

import java.sql.Date;

@Getter
@Setter
@Entity
@Table(name = "exchange-rate")
public class ExchangeRate {
   @Id
   @GeneratedValue(strategy=GenerationType.AUTO)
   private Integer transactionId;
   private String sourceCurrency;
   private String targetCurrency;
   private double amount;
   private Date lastUpdated;
}

This class is essentially a blueprint for storing currency exchange rate data in our database. It uses the libraries and dependencies added earlier. Lombok handles all the repetitive getter/setter boilerplate so you don't have to write it yourself, while JPA annotations like @Entity and @Table tell Spring, "hey, this class maps to a database table called exchange-rate."

Inside the class, there are five fields that become database columns:

• A self-incrementing transactionId as the primary key.

• sourceCurrency and targetCurrency to track which currencies are being converted,

• The amount holding the actual exchange rate

• lastUpdated date, so you always know how fresh your data is.

To store the data, create a repository file in main > java > com.. > repository > ExchangeRateRepository:

package com.example.springbootmysqleks.repository;

import com.example.springbootmysqleks.model.ExchangeRate;
import org.springframework.data.jpa.repository.JpaRepository;

public interface ExchangeRateRepository extends JpaRepository<ExchangeRate, Integer> {
   ExchangeRate findBySourceCurrencyAndTargetCurrency(String sourceCurrency, String targetCurrency);
}

This file acts as the middleman between your code and the database. By simply extending JpaRepository, you instantly get a whole suite of built-in database operations (like save, delete, findAll, and so on) completely for free, without writing a single SQL query.

The interface is typed to work with the ExchangeRate model we just looked at, using Integer as the primary key type.

The one custom method, findBySourceCurrencyAndTargetCurrency, is where Spring's magic really shines. Just by following a naming convention, Spring automatically figures out the SQL query it needs to run, so you can look up an exchange rate by simply passing in two currency codes like "USD" and "EUR" without writing any query logic yourself.

To use the findBySourceCurrencyAndTargetCurrency method, create a service file in main > java > com.. > service > ExchangeRateService with the code below:

package com.example.springbootmysqleks.service;

import com.example.springbootmysqleks.model.ExchangeRate;
import com.example.springbootmysqleks.repository.ExchangeRateRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class ExchangeRateService {

   @Autowired
   private ExchangeRateRepository exchangeRateRepository;

   public ExchangeRate addExchangeRate(ExchangeRate exchangeRate) {
       return exchangeRateRepository.save(exchangeRate);
   }

   public double getAmount(String sourceCurrency, String targetCurrency) {
       ExchangeRate exchangeRate =  exchangeRateRepository.findBySourceCurrencyAndTargetCurrency(sourceCurrency, targetCurrency);
       return exchangeRate == null ? 0 : exchangeRate.getAmount();
   }
}

Here, we created a @Service class that interacts with the repository.

The class has two methods, the addExchangeRate, which simply takes an ExchangeRate object and saves it to the database, and getAmount, which takes a source and target currency, uses our custom repository method to look up the matching record, and then either returns the exchange rate amount or a safe default of 0 if no record is found.

That little ternary check (exchangeRate == null ? 0 : exchangeRate.getAmount()) ensures the app doesn't crash if you query a currency pair that doesn't exist in the database yet.

In main > java > com.. > controller > ExchangeRateService, we have the following code:

package com.example.springbootmysqleks.controller;

import com.example.springbootmysqleks.model.ExchangeRate;
import com.example.springbootmysqleks.service.ExchangeRateService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
public class ExchangeRateController {

   @Autowired
   ExchangeRateService exchangeRateService;

   @GetMapping("/getAmount")
   public double getAmount(@RequestParam String sourceCurrency, @RequestParam String targetCurrency) {
       return exchangeRateService.getAmount(sourceCurrency, targetCurrency);
   }

   @PostMapping("/addExchangeRate")
   public ExchangeRate addExchangeRate(@RequestBody ExchangeRate exchangeRate) {
       return exchangeRateService.addExchangeRate(exchangeRate);
   }

   @GetMapping("/")
   public String getHealth() {
       return "up";
   }

}

The @RestController annotation tells Spring this class will be serving up REST API endpoints, and again @Autowired wires in the service layer automatically.

There are three endpoints:

1. a GET request to /getAmount that accepts sourceCurrency and targetCurrency as query parameters and returns the exchange rate amount

2. a POST request to /addExchangeRate that accepts a full ExchangeRate object as a JSON body and saves it to the database

3. and finally a simple health check endpoint at / that just returns "up",  which is a common pattern in cloud deployments to let load balancers and orchestration tools know the app is alive and running.

Step 6: Configure SpringBoot App for Database

Now, it’s time to configure the application for the database. Navigate to src > main > resources > application.properties, and you should see this:

spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.datasource.url=jdbc:mysql://\({MYSQL_HOSTNAME}:\){MYSQL_PORT}/${MYSQL_DATABASE}?createDatabaseIfNotExist=true
spring.datasource.username=${MYSQL_USERNAME}
spring.datasource.password=${MYSQL_PASSWORD}

spring.jpa.hibernate.ddl-auto=update

spring.jpa.show-sql: true

These are the configurations that allow your app to connect with the database.

• spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver: The driver class for the MySQL database.

• spring.datasource.url=jdbc:mysql://\({MYSQL_HOSTNAME}:\){MYSQL_PORT}/${MYSQL_DATABASE}?createDatabaseIfNotExist=true: This is the data source URL in which we are using the MySQL hostname (127.0.0.1), port name, and database name.

• spring.datasource.username=${MYSQL_USERNAME}: your database user name.

• spring.datasource.password=${MYSQL_PASSWORD}: your database password.

One thing to note: the process of configuring environment variables with your actual credentials varies depending on the IDE you're using. If you're using IntelliJ IDEA, this process is pretty straightforward. If you're using VS Code, the process is different.

To configure your actual credentials for the env variables, create a .vscode/launch.json file in your project root folder and paste in the following configuration:

{
 "version": "0.2.0",
 "configurations": [
   {
     "type": "java",
     "name": "Spring Boot App",
     "request": "launch",
     "mainClass": "com.example.springbootmysqleks.SpringbootMysqlEksApplication",
     "projectName": "springboot-mysql-eks",
     "env": {
       "MYSQL_HOSTNAME": "localhost",
       "MYSQL_PORT": "3306",
       "MYSQL_DATABASE": "exchangedb",
       "MYSQL_USERNAME": "root",
       "MYSQL_PASSWORD": "CHANGE_ME"
     }
   }
 ]
}

Configure the credentials to use your actual credentials.

Now, when you run the app, you should be able to see the created exchangedb table in DBeaver:

Use an API testing tool like Postman to send a POST request to the database:

Next, run the select * from exchange_rate er script in the exchangedb SQL script editor:

At the bottom of the editor, you should see the created table from the Postman request.

Now, run a GET request to the endpoint below:

http://localhost:8080/getAmount?sourceCurrency=USD&targetCurrency=EUR&transactionId=1

You should get a 200 OK response with the currency exchange value, for example, 0.93.

Step 7: Dockerize the SpringBoot Application

To Dockerize your application, create a file named Dockerfile and paste in the configuration below:

FROM eclipse-temurin:17-jre-jammy
WORKDIR /app
COPY build/libs/springboot-mysql-eks.jar /app
EXPOSE 8080
CMD ["java", "-jar", "springboot-mysql-eks.jar"]

Our Dockerfile starts by pulling the lightweight eclipse-temurin:17-jre-jammy base image to keep things lean, then sets /app as the working directory inside the container. It copies our compiled Spring Boot JAR file from the local build/libs/ folder into that directory, exposes port 8080 for incoming traffic, and finally runs the app with java -jar when the container starts up.

Next, build the app to create the .jar file. To do that, run the command below:

./gradlew clean assemble 

You should get a successful build output as shown below:

Navigate to build > the libs folder. You’ll see the springboot-mysql-eks file created.

If you run into an “operation couldn’t be completed.” error, try running the export commands to fix this issue. If you’re using a Mac, then run the command below:

brew install openjdk@21

Next, run the export commands:

export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home

export PATH=\(JAVA_HOME/bin:\)PATH

Then run the ./gradlew clean assemble command again.

Step 8: Push the Image to Elastic Container Registry (ECR)

In this next step, we’ll create an Amazon ECR and push our image to the registry.

To get started, head back into your AWS Console and search for “ECR”. On the ECR page, click Create**.** Then, enter a repository name, for example, “springboot-mysql-eks.” Next, click Create.

Next, select the repo and click View push commands at the top of the page. This presents a window with a bunch of commands you can use to push your image to the registry. Open your terminal and run these commands. You'll need to ensure Docker is running on your local machine before running the commands.

After running the commands, you should see that your image has been successfully pushed to the registry.

Step 9: Implement AWS App Load Balancer

Before getting started with this step, make sure you check out the installation steps and link to additional AWS documentation in the project README. This will help you follow along.

Now, to get started, create a new folder in your root directory named cluster . This is where you'll download the AWS IAM policy for the load balancer. To download the policy, go into your terminal and cd into cluster, then run the command below:

curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.14.1/docs/install/iam_policy.json

This command is gotten from the AWS documentation. Now, when you go to the folder, you’ll see an iam_policy.json file automatically generated.

Next, apply the IAM policy using the command below:

aws iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy.json

You should get an output like this in your terminal:

This shows that the IAM policy has been successfully created. To confirm this, head over to the IAM section in your console, navigate to Policies**,** and search for “AWSLoad…”. You should see the policy created there.

The next step is creating the Kubernetes service account. But before that, you need to tag your public and private subnets as described in this documentation.

Now, head over to the VPC dashboard, navigate to Subnets, click into a subnet, and navigate to Tags. Then, click Manage tags.

Click Add new tag, then enter the key/pair value in the documentation.

Step 10: Create a Cluster in EKS

To create a Kubernetes cluster on EKS, you need the eksctl CLI. Follow the instructions in the AWS eksctl documentation to install the CLI. Next, you need a config file schema to create the cluster. To use this schema, create a new file called cluster.yaml in the cluster folder.

Next, paste in the following configurations:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: spring-test-cluster
  region: us-east-1
  version: "1.30"

vpc:
  id: "<your-vpc-id>"
  subnets:
    private:
      us-east-1a:
        id: "<your-private-subnet-1a-id>" # spring-demo-subnet-private1-us-east-1a
      us-east-1b:
        id: "<your-private-subnet-1b-id>" # spring-demo-subnet-private2-us-east-1b
    public:
      us-east-1a:
        id: "<your-public-subnet-1a-id>" # spring-demo-subnet-public1-us-east-1a
      us-east-1b:
        id: "<your-public-subnet-1b-id>" # spring-demo-subnet-public2-us-east-1b

nodeGroups:
  - name: ng-1
    labels: { role: backend }
    instanceType: t2.micro
    desiredCapacity: 3
    minSize: 3
    maxSize: 5
    privateNetworking: true
    ssh:
      allow: true
      publicKeyName: <your-ec2-key-name>
    iam:
      withAddonPolicies:
        imageBuilder: true
        awsLoadBalancerController: true
        autoScaler: true
iam:
  withOIDC: true
  serviceAccounts:
    - metadata:
        name: aws-load-balancer-controller
        namespace: kube-system
      attachPolicyARNs:
        - arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:policy/AWSLoadBalancerControllerIAMPolicy

Th ClusterConfig file is used by eksctl to create our EKS cluster called spring-test-cluster in the us-east-1 region, running Kubernetes version 1.30. It plugs into our existing VPC, placing the worker nodes across private subnets in two availability zones us-east-1a and us-east-1b) for high availability, while keeping public subnets available for the load balancer.

The node group spins up t2.micro EC2 instances with a desired count of 3 (scaling up to 5 if needed), all with private networking enabled for security. It also sets up the necessary IAM permissions for the AWS Load Balancer Controller, Auto Scaler, and ECR image access so our cluster has everything it needs to manage traffic and pull our Docker images automatically.

Now, after updating your configuration with your credentials, run the command below:

eksctl create cluster -f cluster.yaml

This creates the cluster. You should see an output like this on your terminal:

Now, in your AWS console, navigate to CloudFormation, and you’ll see your cluster creation process in progress.

Now, when you go into the EC2 instance page, you should see the three nodes created.

Step 11: Install AWS Load Balancing

The next step is installing a load balancer for our application. To get started, run the command below:

 kubectl apply -k "github.com/aws/eks-charts/stable/aws-load-balancer-controller/crds?ref=master"

This installs custom resource definitions (CRDs) for our controller. Next, run the command below to add the Helm chart repo.

helm repo add eks https://aws.github.io/eks-charts

Update your local repo to ensure you have the most recent charts:

helm repo update eks

Next, install the Helm chart:

helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
  -n kube-system \
  --set clusterName=my-cluster \
  --set serviceAccount.create=false \
  --set serviceAccount.name=aws-load-balancer-controller \
  --version 1.14.0

Next, verify that the controller is installed:

kubectl get deployment -n kube-system aws-load-balancer-controller

You should see this on your terminal:

This indicates that your controller is ready.

Step 12: Create and Deploy Kubernetes

To get started, you'll first need to create a Kubernetes manifest file. For that, we’ll use Helm Chart.

helm create ytchart

The command above creates a folder named ytchart with the templates for the components. In this folder, you need to make some configurations for your use case. First, navigate to ytchart > templates and delete the serviceaccount.yaml file, since we already created the service account earlier.

Next, go to values.yaml and make the following changes:

• For repository, navigate to the ECR service page on the AWS Console and copy the image URI.

• Tag is latest.

• Set database name

mysql:
 databaseName: exchangedb

• Change service account creation to false.

• Scroll down a bit more and change the service type to NodePort and port to 8080.

You also need to store the database username and password using secrets. Navigate to the templates folder and go into the file named secrets.yaml. Here, set your database username and password, then comment out the liveness and readiness probe in deployment.yaml.

Next, we’ll create a service to connect to the database. To do that, navigate to the mysql.yaml file, then for externalName. Navigate to the RDS service page on the AWS console and copy the database endpoint.

Now, in the deployment.yaml file, paste in the following configuration:

          env:
            - name: SPRING_DATASOURCE_URL
              value: jdbc:mysql://spring-mysql:3306/{{ .Values.mysql.databaseName }}?createDatabaseIfNotExist=true&characterEncoding=UTF-8&useUnicode=true&useSSL=false&allowPublicKeyRetrieval=true
            - name: SPRING_DATASOURCE_USERNAME
              valueFrom:
                secretKeyRef:
                  name: mysql-username
                  key: username
            - name: SPRING_DATASOURCE_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: mysql-root-password
                  key: password

You have successfully created environment variables to secure your database credentials.

In the ingress.yaml file, paste in the following configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: "spring-microservice-ingress"
  annotations:
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/load-balancer-name: spring-alb-test
  labels:
    app: spring-microservice
spec:
  ingressClassName: alb
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ include "ytchart.fullname" . }}
                port:
                  number: 8080

This is your configuration for the ingress service.

Run the command below to see all your configuration values:

helm template ytchart/

Next, run the command below to deploy the chart:

helm install mychart ytchart

You should see an output like this on your terminal:

Now, when you run kubectl get all, you should see this:

Now, navigate to EC2 > Load balancers, copy the DNS name, and enter it into a browser. You should see the “up” text. This indicates that your application is working properly.

Now, when you call the API using the DNS URL as such:

http://spring-alb-test-260424558.us-east-1.elb.amazonaws.com/addExchangeRate

You should get a 200 OK response. Congratulations, you have successfully deployed a SpringBoot app in Kubernetes!

Step 13: Delete Cluster

If you’re familiar with AWS and the cloud, you should already be aware of how costly it can be to leave resources running for extended periods, especially when you’re not using them actively.

Now that we've come to the end of this tutorial, it’s time to delete the resources.

These are the resources to delete:

• RDS database.

• Cluster using the command eksctl delete cluster -f cluster.yaml.

• Navigate to VPC and delete the NAT Gateway

Conclusion

Deploying a Spring Boot application with MySQL on Amazon EKS involves a lot of moving parts, but each step builds logically on the last.

In this tutorial, you've gone from setting up a VPC and provisioning a managed database to containerizing your app, pushing it to ECR, and finally orchestrating everything with Kubernetes and an Application Load Balancer.

What you get is a production-grade setup with high availability, private networking, secure credential management, and auto-scaling built in. This is the kind of infrastructure that would take significant manual effort to replicate without managed services like EKS and RDS.

As a next step, consider adding HTTPS support via AWS Certificate Manager, setting up horizontal pod autoscaling, or integrating a CI/CD pipeline to automate future deployments. And remember to clean up your AWS resources when you're done experimenting. Your wallet will thank you.