<![CDATA[ software architecture - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ https://cdn.freecodecamp.org/universal/favicons/favicon.png <![CDATA[ software architecture - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ Eleventy Tue, 22 Sep 2026 21:39:10 +0000 60 <![CDATA[ How to Migrate a Legacy Monolith Incrementally Without a Big-Bang Rewrite ]]> https://www.freecodecamp.org/news/migrate-legacy-monolith-incrementally/ 6aac7747d406d7c207351312 Thu, 17 Sep 2026 23:27:03 +0000 Large legacy migrations often fail long before the final cutover.

The failure usually starts when the migration is framed as a single event. Move the application. Move the database. Move all the users. Switch the traffic. Turn the old system off.

That creates a dangerous assumption: the legacy system and the new system need to exchange places all at once.

They usually don't.

If you already understand the legacy behavior, protect it with characterization tests, create migration-friendly boundaries, and compare old and new implementations, you have another option.

You can migrate one capability at a time. That changes the problem completely.

Instead of:

legacy monolith
      ↓
complete rewrite
      ↓
big-bang cutover

you can move toward:

legacy monolith
      ↓
one capability extracted
      ↓
small percentage of traffic
      ↓
observe
      ↓
expand
      ↓
repeat

The goal isn't to make the migration slower. The goal is to make each change smaller, observable, and reversible.

In this tutorial, I'll show you how to migrate a legacy monolith incrementally by:

  • choosing a safe first migration slice

  • defining a boundary between legacy and new code

  • routing requests between implementations

  • using the Strangler Fig pattern

  • migrating by business capability instead of technical layer

  • keeping old and new implementations running together

  • introducing progressive traffic

  • detecting failures before full cutover

  • designing rollback paths

  • handling data ownership carefully

  • removing migrated legacy behavior

  • using AI without turning an incremental migration into an automated rewrite

The examples use TypeScript, but the approach applies to most languages, runtimes, and architectures.

The objective is simple: make migration a sequence of controlled changes instead of one irreversible event.

Prerequisites

To follow along, you should be comfortable with:

  • TypeScript or a similar language

  • API and service boundaries

  • integration testing

  • dependency injection

  • routing and reverse proxies

  • database transactions

  • observability

  • incremental refactoring

  • legacy modernization

You should also already understand the behavior of the capability you want to migrate.

Ideally, you know:

  • its inputs

  • its outputs

  • its important business rules

  • its side effects

  • its dependencies

  • its external contracts

  • how you'll detect behavioral differences

If you haven't reached that point yet, migration may be premature.

Table of Contents

Why Big-Bang Migrations Are So Risky

Imagine a legacy commerce application.

It contains:

customers
orders
payments
inventory
shipping
invoicing
notifications
reporting

The modernization plan says:

replace the monolith

That sounds like one project.

Operationally, it may mean changing:

runtime
framework
database
deployment model
API contracts
authentication
networking
observability
data model
business logic
external integrations

at the same time.

If the final cutover fails, the number of possible causes is enormous.

For example:

Did pricing change?

Did the database migration lose data?

Is the payment provider failing?

Did authentication behave differently?

Did the new runtime change date handling?

Did a timeout become shorter?

Did an event stop being published?

Did the new deployment configuration fail?

This is one of the central problems with big-bang migration: too many variables change together.

Incremental migration tries to reduce the number of changing variables at each step.

Think in Migration Slices, Not Applications

Instead of asking:

How do we migrate this monolith?

ask:

What's the smallest meaningful business capability we can move independently?

For example:

Calculate Order Total
Generate Invoice
Send Order Confirmation
Create Shipment
Renew Subscription
Approve Customer

A migration slice should ideally have:

clear input
clear output
known side effects
understood dependencies
observable behavior
a rollback path

That gives you something concrete to move.

For example:

Generate Invoice

might become:

input:
orderId

behavior:
load order
calculate taxes
generate invoice number
create invoice

side effects:
store invoice
publish invoice.created

output:
invoice

That's much easier to migrate than:

billing module

or:

src/services/

Business capabilities make better migration units than folders.

Choose the First Capability Carefully

The first slice matters.

I would usually avoid starting with the most critical capability in the system.

You want something meaningful enough to validate the migration approach, but not so dangerous that a mistake creates catastrophic consequences.

A useful first slice often has:

moderate traffic
limited external dependencies
clear behavior
good test coverage
few transactional boundaries
low blast radius

For example:

Generate Customer Statement

may be a better first migration candidate than:

Authorize Payment

The first migration is partly technical work, but it's also a learning exercise.

You're validating:

routing
deployment
observability
rollback
data access
testing
team workflow

before applying the pattern to more critical capabilities.

Create a Boundary Between Legacy and New

Suppose the legacy application has:

async function generateInvoice(
  orderId: string
) {
  // legacy implementation
}

Before migration, introduce a boundary:

interface InvoiceGenerator {
  generate(
    orderId: string
  ): Promise<Invoice>;
}

The legacy implementation becomes:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // existing behavior
  }
}

The new implementation becomes:

class NewInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // migrated behavior
  }
}

Now the caller doesn't need to know which implementation is active.

That creates an important capability:

replace implementation
without replacing caller

which is one of the foundations of incremental migration.

Use the Strangler Fig Pattern

A common way to describe incremental replacement is the Strangler Fig pattern.

Instead of replacing the entire application at once, new behavior gradually grows around the old system.

Conceptually:

            incoming request
                   │
                   ↓
                router
              /        \
             /          \
      legacy path     new path

At first:

legacy: 100%
new:      0%

Later:

legacy: 95%
new:      5%

Then:

legacy: 50%
new:     50%

Eventually:

legacy:  0%
new:    100%

At that point, the old implementation for that capability can be removed.

The key is that the replacement happens gradually. The legacy application continues serving parts of the system while the new implementation takes over others.

Migrate Capabilities, Not Technical Layers

One tempting migration strategy is:

move database
then move services
then move APIs
then move UI

That can create long periods where every capability spans both old and new architecture.

For example:

new API
↓
legacy service
↓
new database
↓
legacy event publisher

This is sometimes unavoidable.

But whenever possible, I prefer vertical slices.

A vertical slice might be:

Generate Invoice

request
↓
application logic
↓
persistence
↓
events
↓
response

That capability can move as one coherent unit.

Then:

Create Shipment

can move separately.

Then:

Renew Subscription

and so on.

This gives you working migrated capabilities earlier. It also reduces the number of temporary cross-system dependencies.

Keep Legacy and New Implementations Running Together

During an incremental migration, coexistence is normal.

For some period of time, you may have:

LegacyInvoiceGenerator
NewInvoiceGenerator

both deployed.

That's not duplication by accident. It's part of the migration strategy.

The important question is how requests choose between them.

You may use:

feature flag
tenant
user group
request header
region
percentage rollout
specific account IDs

For example:

class InvoiceRouter {
  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    orderId: string,
    useMigrated: boolean
  ) {
    if (useMigrated) {
      return this.migrated.generate(
        orderId
      );
    }

    return this.legacy.generate(
      orderId
    );
  }
}

This is deliberately simple. The important part is that routing is explicit. You know which implementation handled each request.

Route Traffic Explicitly

Avoid migration logic that's difficult to observe.

For example:

try {
  return await newService.call();
} catch {
  return legacyService.call();
}

This may look resilient, but it can hide failures.

Suppose the new implementation fails 40% of the time. If every failure silently falls back to legacy, users may see no problem. But the migration isn't healthy.

The problem is that the first version mixes two decisions together: which implementation should receive the request and what should happen when that implementation fails. Because the fallback happens inside the catch, the migrated path can fail repeatedly without producing an explicit routing signal that you can measure.

A better approach is to make the routing decision first, record it, and then call the selected implementation. That separates migration policy from error handling and gives you a clear record of how much traffic actually reached each path.

For example:

const route =
  migrationPolicy.route(request);

metrics.increment(
  `invoice.route.${route}`
);

if (route === "migrated") {
  return migrated.generate(
    request.orderId
  );
}

return legacy.generate(
  request.orderId
);

Now you can measure:

requests routed to legacy
requests routed to migrated
migration failures
fallback count
latency
business outcomes

Migration should be observable as a first-class system behavior.

Start with Internal or Low-Risk Traffic

Before routing a large percentage of customers to the migrated path, start with safer traffic.

For example:

development
test environments
internal users
staff accounts
test tenants
specific low-risk customers

This lets you validate:

deployment
routing
observability
data access
external integrations
failure handling

with lower risk.

You can then expand.

For example:

internal users
↓
1% production
↓
5%
↓
10%
↓
25%
↓
50%
↓
100%

The exact percentages aren't important, but the principle is.

Each increase should happen because the previous stage produced enough evidence.

Progressively Increase Production Traffic

Suppose you have:

10,000 invoice requests/day

Instead of switching all requests:

legacy → new

at once, route:

1%

first.

That gives roughly:

100 real requests/day

through the migrated path.

Now monitor:

error rate
latency
output differences
side effects
customer-visible failures
business metrics

If the system behaves correctly, increase traffic. If it doesn't, reduce or disable migrated routing.

The migration becomes a controlled experiment. That's very different from a cutover event.

Use Differential Testing Before and During Rollout

The previous article in this series focused on differential testing. That technique becomes especially useful here.

Differential testing means running the legacy and migrated implementations with the same input and comparing their observable behavior. Depending on the capability, that may include return values, errors, state changes, and side effects.

The goal isn't to prove that the implementations are internally identical. It's to detect meaningful behavioral differences before those differences reach all of your production traffic.

Before live routing, you can compare:

same input
↓
legacy result

same input
↓
new result

During rollout, you can also sample real traffic and compare behavior where it is safe to do so.

For example:

real request
      │
      ├────→ active implementation
      │
      └────→ shadow implementation

Then compare:

output
errors
side effects
business state

This gives you evidence before increasing traffic.

A rollout decision can then be based on:

divergence
error rate
latency
business outcomes

instead of:

It seems fine.

A Small End-to-End Invoice Migration Example

The individual pieces are easier to understand when you see them working together.

Here's a deliberately small, in-memory example based on the invoice capability we've been using throughout the article. It doesn't include a real database, reverse proxy, queue, or deployment platform. The point is to show the migration control flow in one place.

Start with a shared contract:

type InvoiceInput = {
  orderId: string;
  subtotal: number;
};

type Invoice = {
  orderId: string;
  total: number;
};

interface InvoiceGenerator {
  generate(
    input: InvoiceInput
  ): Promise<Invoice>;
}

The legacy implementation calculates the invoice total like this:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    return {
      orderId: input.orderId,
      total: input.subtotal * 1.21,
    };
  }
}

Now imagine we've migrated that capability into a new implementation:

class MigratedInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const tax =
      input.subtotal * 0.21;

    return {
      orderId: input.orderId,
      total: input.subtotal + tax,
    };
  }
}

The code is different, but the intended behavior is the same.

Next, define a deterministic rollout function. This example assigns each orderId to a bucket from 0 to 99 so the same order always follows the same route:

function bucketFor(
  value: string
): number {
  const sum = [...value].reduce(
    (total, char) =>
      total + char.charCodeAt(0),
    0
  );

  return sum % 100;
}

function shouldUseMigrated(
  orderId: string,
  percentage: number
): boolean {
  return (
    bucketFor(orderId) < percentage
  );
}

If percentage is 10, roughly 10% of IDs will be assigned to the migrated path.

Now add some tiny in-memory metrics:

const metrics = {
  legacyRequests: 0,
  migratedRequests: 0,
  mismatches: 0,
};

Then put the legacy and migrated implementations behind one migration-aware entry point:

class IncrementalInvoiceService {
  migratedEnabled = true;
  rolloutPercentage = 10;

  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const legacyResult =
      await this.legacy.generate(
        structuredClone(input)
      );

    const migratedResult =
      await this.migrated.generate(
        structuredClone(input)
      );

    if (
      migratedResult.orderId !==
        legacyResult.orderId ||
      migratedResult.total !==
        legacyResult.total
    ) {
      metrics.mismatches += 1;
    }

    const useMigrated =
      this.migratedEnabled &&
      shouldUseMigrated(
        input.orderId,
        this.rolloutPercentage
      );

    if (useMigrated) {
      metrics.migratedRequests += 1;
      return migratedResult;
    }

    metrics.legacyRequests += 1;
    return legacyResult;
  }
}

This small service combines several ideas from the article.

First, it runs both implementations with the same input and compares their results. Because this example is entirely in memory and has no external side effects, doing that is safe.

Second, it routes only a percentage of requests to the migrated result.

Third, it records how many requests used each path and how many behavioral mismatches occurred.

You can exercise it with a few requests:

const service =
  new IncrementalInvoiceService(
    new LegacyInvoiceGenerator(),
    new MigratedInvoiceGenerator()
  );

for (let i = 1; i <= 100; i++) {
  await service.generate({
    orderId: `order-${i}`,
    subtotal: 1000,
  });
}

console.log(metrics);

You might see something like:

legacyRequests:   89
migratedRequests: 11
mismatches:        0

The exact split may not be exactly 90/10 with only 100 inputs because the bucket function is intentionally simple. The important point is that routing is deterministic, measurable, and controlled by rolloutPercentage.

If the migrated implementation starts producing differences, the mismatch counter gives you an observable signal.

And if you decide the rollout should stop, rollback is explicit:

service.migratedEnabled = false;

From that point forward, all returned responses come from the legacy implementation again.

This is intentionally a simplified example. A production system would need stronger routing, real metrics, error handling, persistent state, and careful treatment of side effects.

In particular, you shouldn't blindly execute both implementations if generating an invoice sends email, writes to two production databases, charges a customer, or publishes externally visible events. In those cases, the shadow path needs recording adapters, isolated infrastructure, or another mechanism that lets you compare behavior without duplicating real effects.

But the control loop is the same:

same input
↓
compare legacy and migrated behavior
↓
route a small percentage
↓
observe
↓
expand or roll back

That is incremental migration in its smallest useful form.

Design Rollback Before You Need It

Rollback shouldn't be invented during an incident. Before moving traffic, ask what happens if the migrated path fails.

For routing-level migrations, rollback may be simple:

migration flag = false

and traffic returns to:

legacy implementation

For example:

if (
  featureFlags.useNewInvoices
) {
  return migrated.generate(
    orderId
  );
}

return legacy.generate(orderId);

If the migrated path behaves incorrectly:

useNewInvoices = false

Rollback is almost immediate.

But rollback becomes more complicated when:

data format changes
new data is written
events differ
external systems are updated
legacy code cannot read new records

In those cases, rollback may require more than flipping a feature flag. You might need backward-compatible schemas so both versions can read the same records, compensating actions for external side effects, replayable events, reconciliation jobs, or a short period where the legacy system remains able to consume data written by the new path.

For higher-risk migrations, it can also help to define a rollback boundary in advance. For example: traffic can return to legacy until a new schema version is written, or after a particular external event is emitted, recovery requires compensation instead of a simple rollback. The important part is knowing when rollback is still reversible and when you've crossed into a different recovery strategy.

That's why rollback design needs to happen before deployment.

Treat Data Migration as a Separate Problem

Application migration and data migration are related, but they aren't the same problem.

Suppose the legacy system stores:

{
  "customer_type": "P",
  "status": 2
}

while the new system stores:

{
  "customerType": "PREMIUM",
  "status": "APPROVED"
}

You now need to answer:

Which database is authoritative?

Can both systems read the same data?

Do we transform on read?

Do we migrate records in batches?

Do we replicate changes?

When does ownership change?

These decisions should be explicit. Otherwise the application migration may appear successful while the data boundary remains ambiguous.

Be Careful with Dual Writes

One common transition strategy is:

write to legacy database
+
write to new database

This is called dual writing, and it looks simple.

For example:

await legacyOrders.save(order);
await newOrders.save(order);

But what happens if:

legacy write succeeds
new write fails

Now the two systems disagree.

Or:

legacy write fails
new write succeeds

Same problem.

Dual writes create a distributed consistency problem.

If you use them, you need to think about:

retries
idempotency
reconciliation
ordering
partial failure
monitoring

Sometimes a safer approach is:

single authoritative write
↓
change event
↓
replication

or a transactional outbox.

There's no universal solution. The important point is not to treat dual writing as a trivial migration technique.

Decide Who Owns the Data

During coexistence, data ownership can become confusing.

Imagine:

legacy system writes customers

new system writes invoices

both systems read orders

That may be perfectly reasonable, but it should be documented.

For each migrated capability, define:

system of record
write owner
readers
replication direction
consistency expectations

For example:

Invoices

Write owner:
new system

Source of truth:
new database

Legacy access:
read-only adapter

Replication:
new → legacy reporting store

Now the architecture has an explicit direction.

Without ownership rules, migrations often create permanent synchronization problems.

Observe Business Behavior, Not Just Infrastructure

During rollout, teams often monitor:

CPU
memory
latency
HTTP 500s
database connections

Those are important. But they're not enough.

Suppose:

HTTP 200 rate = 99.99%

while:

invoice totals are wrong

Infrastructure monitoring says:

healthy

But the business system is not healthy.

Migration observability should include domain signals.

For example:

orders processed
payments authorized
invoices generated
discount distribution
failed renewals
average invoice total
events published

If you know normal business behavior, unusual changes can expose migration defects that technical metrics miss.

Know When a Migration Slice Is Complete

A capability isn't fully migrated just because traffic reached 100%.

Before declaring it complete, I would verify:

100% traffic on new path
acceptable error rate
acceptable latency
behavioral differences resolved
side effects verified
data ownership established
rollback window completed
legacy callers removed
legacy writes stopped
observability in place

Then ask:

Is the legacy implementation still serving any purpose?

If not, remove it.

Leaving both implementations permanently active creates:

maintenance cost
confusion
duplicate bugs
unclear ownership
future migration debt

Incremental migration should eventually simplify the system, not permanently duplicate it.

Remove the Legacy Path

This step is often delayed.

Teams migrate traffic but leave the old path in place:

just in case

Months later:

nobody knows whether it is still used

Before deleting it, verify:

routing metrics show zero traffic
no callers depend on it
data dependencies are removed
rollback period is complete
operational documentation is updated

Then remove:

legacy implementation
legacy feature flags
legacy database access
unused integration code
temporary compatibility layers

Deletion is part of migration.

A migration that only adds new architecture without removing old architecture can increase complexity rather than reduce it.

How to Use AI During an Incremental Migration

AI can help with many parts of this process.

For example, it can inspect the legacy codebase and help answer:

Which modules implement this capability?

Which callers depend on it?

Which database tables does it touch?

Which external services does it call?

Which side effects occur?

Which feature flags already exist?

Which paths need adapters?

A useful prompt might be:

Analyze the Generate Invoice capability.

Identify:

1. entry points,
2. business rules,
3. persistence dependencies,
4. external integrations,
5. side effects,
6. callers,
7. data ownership,
8. possible migration seams.

Do not redesign the system.

Return evidence for each finding using file paths
and relevant code references.

AI can also help compare migration changes.

For example:

Compare the legacy and migrated implementations.

Identify possible behavioral differences in:

- return values,
- errors,
- side effects,
- persistence,
- event ordering,
- retries,
- idempotency,
- transaction boundaries.

Do not assume the new implementation is correct.

This is useful because migration involves a lot of repetitive analysis, and AI can accelerate that analysis.

Don't Let AI Turn the Migration into a Rewrite

There's a common failure mode.

You ask:

Help me migrate this legacy capability.

The model responds with:

new architecture
new domain model
new API
new event model
new database schema
new validation layer
new framework

At that point, you're no longer migrating one capability, you're redesigning it.

Sometimes redesign is necessary, but it should be intentional.

During incremental migration, I prefer prompts with explicit constraints.

For example:

Migrate this capability without intentionally changing
observable behavior.

Preserve:

- inputs,
- outputs,
- errors,
- side effects,
- ordering where relevant,
- transactional behavior.

Only introduce the minimum structural changes required
to run it in the target environment.

List any behavior you cannot preserve with confidence.

That keeps the transformation narrow.

AI should help reduce mechanical effort. It shouldn't silently expand project scope.

A Practical Incremental Migration Workflow

Here's the workflow I would use.

1. Understand the Capability

Identify:

inputs
outputs
rules
side effects
dependencies
unknowns

2. Characterize Existing Behavior

Protect important behavior with:

characterization tests
integration tests
contract tests

3. Refactor for Migration

Create:

seams
adapters
explicit dependencies
clear orchestration

without intentionally changing behavior.

4. Build the New Implementation

Implement the capability in the target environment. Keep its observable contract clear.

5. Differentially Test Old and New

Compare:

outputs
errors
side effects
business state

using representative cases.

6. Introduce Explicit Routing

Allow requests to choose:

legacy
or
migrated

through an observable migration policy.

7. Start with Safe Traffic

Use:

internal users
test tenants
selected customers

8. Increase Traffic Gradually

For example:

1%
5%
10%
25%
50%
100%

only when evidence supports the next stage.

9. Monitor Technical and Business Metrics

Observe both:

system health
business behavior

10. Keep Rollback Available

Make returning to the legacy path fast and understood.

11. Transfer Data Ownership

Explicitly define which system owns:

writes
reads
replication

12. Remove the Legacy Path

After the migration has stabilized:

delete old implementation
remove temporary routing
remove obsolete dependencies

Then choose the next capability.

What Incremental Migration Doesn't Solve

Incremental migration reduces risk, but it doesn't eliminate complexity.

You may still need to deal with:

distributed transactions
shared databases
old schemas
tight coupling
unsupported runtimes
poor test coverage
organizational ownership
regulatory constraints

There are also systems where partial migration is extremely difficult.

For example:

highly stateful systems
strongly coupled desktop applications
large transactional batch systems
systems with shared global state

Sometimes the migration boundary needs to be larger.

The principle remains the same:

Make the smallest reversible change that produces useful migration progress.

Incremental doesn't always mean tiny. It means controlled.

The Complete Legacy Modernization Workflow

This article closes the workflow we've been building throughout this series.

We started with a basic problem:

How do you modernize a legacy application without accidentally turning the project into a rewrite?

The first step was understanding.

Legacy system
↓
investigate
↓
map behavior and dependencies

Then characterization.

observed behavior
↓
tests
↓
behavioral safety net

Then refactoring.

entangled capability
↓
seams and boundaries
↓
migration-friendly structure

Then differential testing.

legacy implementation
        +
new implementation
        ↓
behavior comparison

And finally incremental migration.

Understand
↓
Characterize
↓
Refactor
↓
Migrate
↓
Compare
↓
Route
↓
Observe
↓
Expand
↓
Remove legacy

The sequence matters.

If you skip understanding, you may migrate the wrong behavior.

If you skip characterization, you may not notice behavioral changes.

If you skip refactoring, the migration boundary may remain too large.

If you skip comparison, differences remain hidden.

If you skip incremental rollout, you discover problems at full blast radius.

Each step reduces a different kind of uncertainty.

Conclusion

Modernizing a legacy application doesn't require replacing everything at once.

In many cases, the safer strategy is to create a path where old and new implementations can coexist temporarily.

Move one capability, then compare it.

Route a small amount of traffic and observe what happens.

Increase traffic when the evidence supports it, and roll back when it doesn't.

Transfer ownership explicitly, then remove the legacy path.

And repeat.

The full workflow becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate incrementally
↓
Compare behavior
↓
Progressively route traffic
↓
Observe
↓
Remove legacy

AI can make every stage faster.

It can help map code, identify dependencies, generate adapters, compare implementations, analyze failures, and inspect migration diffs.

But speed isn't the same as confidence.

The important decisions still require engineering judgment:

What behavior matters?

What can change?

What should remain compatible?

What is the migration boundary?

What evidence is enough?

When is rollback necessary?

When can the legacy path be removed?

Those aren't code-generation questions. They're migration decisions.

And that's the larger lesson behind this entire series.

AI makes it increasingly cheap to produce new code. But that doesn't make legacy modernization trivial. It makes the quality of the decisions around the code more important.

Because the safest migration is rarely the one that changes the most software. It's the one that lets you change the system while continuously knowing what changed, why it changed, and whether it's safe to keep going.

]]> <![CDATA[ How to Use Differential Testing During a Legacy Migration ]]> https://www.freecodecamp.org/news/differential-testing-legacy-migration/ 6aa8200e59dfce663a0e73bd Mon, 14 Sep 2026 16:25:50 +0000 The most dangerous moment in a legacy migration isn't necessarily when you start writing the new implementation. It's when the new implementation looks finished.

The code compiles, the tests pass, the architecture is cleaner, and the new service responds faster.

Then everybody starts asking the same question:

Can we switch traffic now?

That's where confidence becomes difficult.

A new implementation can pass its own test suite and still behave differently from the system it is replacing.

Maybe rounding changed, or null values are handled differently, or an error became a successful response.

Maybe records are sorted differently, or a side effect happens in a different order, or a business rule you never documented was lost during the migration.

This is why, during a legacy migration, I like having another source of evidence: run the old and new implementations with the same inputs and compare what they do.

That's the basic idea behind differential testing. Instead of asking only if the new system passes its tests, you also ask: given the same input, where does the new system behave differently from the old one?

Those differences become evidence.

Some are bugs, some are intentional improvements, some are harmless representation differences, and some reveal behavior nobody knew existed.

In this tutorial, I'll show you how to use differential testing during a legacy migration to:

  • Compare old and new implementations

  • Define what should be considered equivalent

  • Normalize outputs before comparing them

  • Handle timestamps and other nondeterministic values

  • Compare errors and side effects

  • Run differential tests automatically

  • Introduce tolerances where exact equality doesn't make sense

  • Analyze mismatches

  • Use shadow traffic in production safely

  • Use AI to classify divergences without letting it decide correctness

  • Determine when the new implementation is ready for cutover

The examples use TypeScript and Vitest, but the approach applies to most languages and migration strategies.

The goal isn't to prove that two implementations are internally identical. It's to obtain evidence that they are behaviorally equivalent where equivalence matters.

Prerequisites

To follow along here, you should be comfortable with:

  • TypeScript or a similar language

  • unit and integration testing

  • asynchronous code

  • API and service boundaries

  • legacy modernization

  • basic observability concepts

You should also already have some understanding of the capability being migrated.

Ideally, you know its inputs, outputs, important business rules, external contracts, side effects, and known areas of uncertainty.

Differential testing works best after you've already created a boundary around the capability you want to migrate.

Table of Contents

What Differential Testing Actually Tells You

Imagine that your legacy application calculates the final price of an order.

The legacy implementation looks like this:

type Order = {
  subtotal: number;
  customerType: "STANDARD" | "PREMIUM";
  country: string;
};

function legacyCalculateTotal(order: Order): number {
  let total = order.subtotal;

  if (order.customerType === "PREMIUM") {
    total *= 0.9;
  }

  if (order.country === "AR") {
    total -= 500;
  }

  return Math.max(total, 0);
}

During the migration, you create a new implementation:

function newCalculateTotal(order: Order): number {
  const premiumDiscount =
    order.customerType === "PREMIUM"
      ? order.subtotal * 0.1
      : 0;

  const countryAdjustment =
    order.country === "AR"
      ? 500
      : 0;

  return Math.max(
    order.subtotal -
      premiumDiscount -
      countryAdjustment,
    0
  );
}

The implementations look different. And that's fine. What matters is whether they produce equivalent behavior.

A simple differential test can run both:

import { describe, expect, it } from "vitest";

describe("order total migration", () => {
  it("matches the legacy implementation", () => {
    const order: Order = {
      subtotal: 10000,
      customerType: "PREMIUM",
      country: "AR",
    };

    const legacy =
      legacyCalculateTotal(order);

    const migrated =
      newCalculateTotal(order);

    expect(migrated).toBe(legacy);
  });
});

For this input:

legacy → 8500
new    → 8500

Good. But one matching example proves very little.

The value comes from systematically asking:

same input
↓
legacy implementation ──→ result A

same input
↓
new implementation ─────→ result B

compare A and B

Every mismatch gives you something to investigate.

Start with One Observable Boundary

Don't begin by comparing entire applications. To start, choose one capability.

For example:

Calculate Order Total
Generate Invoice
Approve Customer
Renew Subscription
Calculate Commission
Create Shipment

Suppose the migration boundary is:

interface OrderProcessor {
  process(order: Order): Promise<ProcessedOrder>;
}

Now you have two implementations:

LegacyOrderProcessor

NewOrderProcessor

That is a useful differential boundary, because both receive the same conceptual input, and both produce the same conceptual output.

You can compare them without requiring their internal architecture to match.

That matters because migrations often change structure intentionally.

The legacy implementation might be:

controller
→ service
→ SQL
→ provider SDK

while the new implementation might be:

use case
→ repository
→ gateway
→ events

Differential testing shouldn't care. It should care about observable behavior.

Run the Legacy and New Implementations with the Same Input

Suppose both implementations expose:

interface OrderProcessor {
  process(order: Order): Promise<ProcessedOrder>;
}

You can create:

const legacyProcessor =
  new LegacyOrderProcessor();

const newProcessor =
  new NewOrderProcessor();

Then:

it("produces the same processed order", async () => {
  const input: Order = {
    id: "order-1",
    subtotal: 10000,
    customerType: "PREMIUM",
    country: "US",
  };

  const legacy =
    await legacyProcessor.process(
      structuredClone(input)
    );

  const migrated =
    await newProcessor.process(
      structuredClone(input)
    );

  expect(migrated).toEqual(legacy);
});

Notice the use of:

structuredClone(input)

That matters if either implementation mutates its input.

Without separate copies, the first execution could influence the second.

You want:

same initial state

not:

new implementation receives state modified by legacy implementation

That kind of contamination can create misleading results.

Don't Compare Raw Output Blindly

The first version of a differential test is often:

expect(newResult).toEqual(legacyResult);

Sometimes that's exactly right. But other times it's wrong.

Imagine the legacy system returns:

{
  "id": "order-1",
  "total": 9000,
  "status": "PROCESSED",
  "generatedAt": "2026-09-09T10:00:01.231Z",
  "requestId": "legacy-f93a"
}

The new system returns:

{
  "requestId": "new-b517",
  "status": "PROCESSED",
  "generatedAt": "2026-09-09T10:00:01.416Z",
  "total": 9000,
  "id": "order-1"
}

A raw object comparison may fail because:

requestId differs
timestamp differs

But the business behavior might be equivalent.

You need to decide which fields are part of the meaningful contract.

Maybe:

id
total
status

matter.

While:

generatedAt
requestId

don't need exact equivalence.

That leads to normalization.

Normalize Values Before Comparing Them

Normalization means transforming outputs into a common representation before comparing them.

The goal isn't to change the business meaning of the data. It's to remove differences that are expected and irrelevant to the comparison, such as generated request IDs or timestamps, so the test can focus on the fields that actually define the behavior you care about.

In practice, that often means creating a canonical representation: a smaller, stable shape that contains only the meaningful fields you want to compare.

For example:

type ProcessedOrder = {
  id: string;
  total: number;
  status: string;
  generatedAt: string;
  requestId: string;
};

function normalizeOrder(
  order: ProcessedOrder
) {
  return {
    id: order.id,
    total: order.total,
    status: order.status,
  };
}

Here, ProcessedOrder contains both business-relevant fields and values that may legitimately differ between executions.

The normalizeOrder() function keeps id, total, and status, while leaving out generatedAt and requestId. That means two results can still be considered equivalent even if they were generated at slightly different times or used different request identifiers.

Now compare:

expect(
  normalizeOrder(migrated)
).toEqual(
  normalizeOrder(legacy)
);

This makes your equivalence rule explicit.

You're saying:

These fields define relevant behavior for this comparison.

Normalization can also handle:

  • ordering

  • casing

  • optional fields

  • timestamps

  • generated identifiers

  • numeric formatting

  • provider-specific metadata

But normalization must be deliberate. If you remove too much, you can hide real migration bugs.

Handle Timestamps and Other Nondeterministic Values

Legacy systems contain many nondeterministic values.

For example:

timestamps
UUIDs
random tokens
request IDs
trace IDs
database-generated IDs
unordered collections
provider-generated references

If you compare those values exactly, your differential suite may fail constantly.

One option is dependency control.

Dependency control means moving a nondeterministic source, such as the current time or an ID generator, behind an interface that you can replace during tests.

Instead of letting each implementation read the real clock independently, you inject the same controlled clock into both. That gives them the same value and removes time itself as a source of meaningless divergence.

Suppose the code uses:

new Date()

You can replace that dependency with a clock:

interface Clock {
  now(): Date;
}

Then both implementations receive:

const clock = {
  now: () =>
    new Date(
      "2026-09-09T10:00:00.000Z"
    ),
};

Now time becomes deterministic.

The same technique can work for ID generation:

interface IdGenerator {
  next(): string;
}

Then tests can provide:

const ids = {
  next: () => "fixed-id",
};

If controlling nondeterminism is impractical, normalize it out only when it's not part of the behavior you need to protect.

Compare Business Meaning, Not Just JSON

Two systems can return different representations while expressing the same business state.

Imagine you have this in your legacy system:

{
  "status": 2
}

And this in your new one:

{
  "status": "APPROVED"
}

Raw comparison says:

different

Business comparison may say:

equivalent

You can create a semantic normalizer:

function normalizeStatus(
  status: number | string
) {
  if (status === 2) {
    return "APPROVED";
  }

  return status;
}

Here, the normalizer translates the legacy numeric value 2 into the business meaning used by the new implementation: "APPROVED".

It doesn't claim that every number and string are interchangeable. It encodes one explicit equivalence rule that you've already decided is valid for this migration.

Then:

expect(
  normalizeStatus(newResult.status)
).toBe(
  normalizeStatus(legacyResult.status)
);

This is especially useful when migration intentionally changes:

database schema
API representation
enumerations
provider-specific formats
internal identifiers

The important question becomes:

Does the observable business meaning remain equivalent?

Not:

Are the bytes identical?

Compare Errors as Part of the Contract

Success responses aren't the whole behavior. Errors matter too.

Suppose the legacy implementation rejects a missing customer:

throw new Error("Customer not found");

The new implementation accidentally returns:

return null;

These two implementations behave very differently for the same invalid input.

The legacy version fails explicitly, while the new version silently returns a value that a caller may interpret as a successful result.

If your differential tests only exercise cases where a valid customer exists, both implementations may appear equivalent and this contract change will remain invisible.

That's why failure behavior has to be compared too.

Create cases that capture errors:

async function captureResult<T>(
  operation: () => Promise<T>
) {
  try {
    return {
      type: "success" as const,
      value: await operation(),
    };
  } catch (error) {
    return {
      type: "error" as const,
      error:
        error instanceof Error
          ? error.message
          : String(error),
    };
  }
}

The helper wraps an asynchronous operation and converts both possible outcomes into data.

If the operation succeeds, it returns an object with type: "success" and the returned value. If the operation throws, the catch block converts that exception into an object with type: "error" and a readable error message.

This gives both implementations the same comparison shape, so the test can compare success versus failure explicitly instead of letting an exception stop the test before the two behaviors can be evaluated.

Now:

const legacy =
  await captureResult(() =>
    legacyProcessor.process(input)
  );

const migrated =
  await captureResult(() =>
    newProcessor.process(input)
  );

expect(migrated.type).toBe(legacy.type);

If errors are contractually important, compare:

error category
HTTP status
error code
retryability
validation details

Don't necessarily compare exact wording unless clients depend on it.

Compare Side Effects, Too

One of the easiest migration mistakes is preserving the return value while losing a side effect.

Suppose both implementations return:

{
  "status": "PROCESSED"
}

But the legacy version also:

persists the order
publishes an event
creates a payment
writes an audit entry

and the new version forgets the audit entry.

Response-level differential testing won't catch that. So you'll want to capture side effects.

For example:

type Effect =
  | {
      type: "payment";
      orderId: string;
      amount: number;
    }
  | {
      type: "event";
      name: string;
      orderId: string;
    };

A test adapter can record them:

class RecordingPaymentGateway {
  effects: Effect[] = [];

  async charge(
    orderId: string,
    amount: number
  ) {
    this.effects.push({
      type: "payment",
      orderId,
      amount,
    });
  }
}

Instead of sending a real payment request, this adapter records what the application attempted to do in the effects array.

You can apply the same idea to event publication:

class RecordingEvents {
  effects: Effect[] = [];

  async publish(
    name: string,
    orderId: string
  ) {
    this.effects.push({
      type: "event",
      name,
      orderId,
    });
  }
}

The application still calls its payment and event dependencies as usual. The test doubles simply capture those calls as structured data instead of performing the real external actions.

After running the legacy and migrated implementations with their own recording adapters, you can compare the two recorded effect lists and verify that both systems attempted the same observable side effects.

Now the differential test can compare:

expect(newEffects).toEqual(legacyEffects);

Again, exact ordering should only be required if ordering matters.

Use Tolerances When Exact Equality Is Wrong

Some domains shouldn't use exact equality.

Imagine a migrated calculation produces:

legacy → 34.333333333
new    → 34.333333334

Is that a migration bug? Maybe not.

Floating-point calculations may justify a tolerance.

For example:

expect(newResult).toBeCloseTo(
  legacyResult,
  6
);

Or define an explicit comparator:

function withinTolerance(
  a: number,
  b: number,
  tolerance: number
) {
  return Math.abs(a - b) <= tolerance;
}

Then:

expect(
  withinTolerance(
    migrated.total,
    legacy.total,
    0.01
  )
).toBe(true);

But tolerances should come from domain requirements. Don't use them just to make failing tests disappear.

For financial systems, one cent can matter. For scientific calculations, a much smaller numerical difference may matter.

Equivalence is a business and engineering decision.

Build a Reusable Differential Test Harness

Once you compare more than a few cases, you can create a reusable harness.

For example:

type DifferentialResult<T> = {
  input: T;
  equivalent: boolean;
  legacy: unknown;
  migrated: unknown;
};

async function compareImplementations<
  TInput,
  TOutput
>(
  input: TInput,
  legacy: (
    input: TInput
  ) => Promise<TOutput>,
  migrated: (
    input: TInput
  ) => Promise<TOutput>,
  normalize: (
    output: TOutput
  ) => unknown
): Promise<
  DifferentialResult<TInput>
> {
  const legacyResult =
    await legacy(
      structuredClone(input)
    );

  const migratedResult =
    await migrated(
      structuredClone(input)
    );

  const normalizedLegacy =
    normalize(legacyResult);

  const normalizedMigrated =
    normalize(migratedResult);

  return {
    input,
    equivalent:
      JSON.stringify(
        normalizedLegacy
      ) ===
      JSON.stringify(
        normalizedMigrated
      ),
    legacy: normalizedLegacy,
    migrated: normalizedMigrated,
  };
}

The harness does four things.

First, it runs the legacy and migrated implementations with separate clones of the same input, so one execution can't mutate the data seen by the other.

Second, it passes both outputs through the same normalize() function. That applies the equivalence rules in one place instead of repeating them in every test.

Third, it compares the normalized results and records whether they're equivalent.

Finally, it returns the input and both normalized outputs together. That makes a failed comparison easier to inspect because the test report can show exactly which case diverged and what each implementation produced.

Then:

const result =
  await compareImplementations(
    input,
    legacyProcessor.process.bind(
      legacyProcessor
    ),
    newProcessor.process.bind(
      newProcessor
    ),
    normalizeOrder
  );

expect(result.equivalent).toBe(true);

For real systems, I would usually avoid relying on JSON.stringify() as the final equality mechanism.

The example keeps the harness readable.

In production-quality tooling, use a proper structural or domain-specific comparator.

The important part is that comparison logic becomes centralized.

Generate Test Cases from Real Behavior

Hand-written examples are useful. But migrations often fail on cases nobody thought to write manually.

Useful sources of inputs include:

existing test fixtures
historical incidents
production-safe request samples
database records
boundary values
previous bug reports
known customer scenarios

Suppose production shows these order shapes:

const cases: Order[] = [
  {
    subtotal: 0,
    customerType: "STANDARD",
    country: "US",
  },
  {
    subtotal: 500,
    customerType: "PREMIUM",
    country: "AR",
  },
  {
    subtotal: 10000,
    customerType: "STANDARD",
    country: "AR",
  },
];

The first block is the test data. It captures a small set of representative input shapes that you've observed in real usage or reconstructed safely from production behavior.

The next block is the test itself. it.each(cases) tells Vitest to run the same differential comparison once for every input in that array.

That separates two concerns: defining realistic cases and defining how every case should be evaluated.

Now:

it.each(cases)(
  "matches legacy behavior",
  async (input) => {
    const legacy =
      await legacyProcessor.process(
        structuredClone(input)
      );

    const migrated =
      await newProcessor.process(
        structuredClone(input)
      );

    expect(
      normalizeOrder(migrated)
    ).toEqual(
      normalizeOrder(legacy)
    );
  }
);

Real examples help expose assumptions that synthetic test data often misses. But production data must be handled carefully.

Remove or anonymize:

personal data
credentials
tokens
financial identifiers
confidential business data

The objective is to preserve useful behavioral shapes, not copy sensitive production information into test fixtures.

Classify Every Difference

A differential failure doesn't automatically mean that the new implementation is wrong.

Suppose you find 200 mismatches. Classify them.

I like categories such as:

migration defect
legacy defect intentionally preserved
intentional behavior change
representation difference
nondeterministic difference
test/comparator defect
unknown

For example:

Input:
subtotal = 5000

Legacy:
discount = 0

New:
discount = 500

Classification:
unknown

Investigation reveals that the new implementation changed:

amount > 5000

to:

amount >= 5000

Now you need a decision.

Was that:

accidental migration change

or:

intentional bug fix

Differential testing exposes the decision. It doesn't make the decision for you.

That's one of its greatest benefits.

How to Use AI to Investigate Differential Failures

Large migrations can produce hundreds or thousands of differences. And AI can help triage them.

Suppose you have:

{
  "input": {
    "subtotal": 5000,
    "country": "AR"
  },
  "legacy": {
    "total": 4500
  },
  "new": {
    "total": 4000
  }
}

You can give the model:

  • the input

  • both outputs

  • relevant legacy code

  • relevant migrated code

  • the comparator rules

Then ask:

Analyze this differential test failure.

Identify the smallest behavioral difference that could
explain the mismatch.

Compare the legacy and migrated implementations.

Return:

1. observed difference,
2. relevant legacy branch,
3. relevant migrated branch,
4. likely cause,
5. evidence supporting the cause,
6. additional test cases that could confirm it.

Do not decide which behavior is correct.
Do not modify the code yet.

That last instruction matters. AI can be very useful for locating why two implementations diverge. It shouldn't silently turn that diagnosis into a business decision.

Don't Let AI Decide Which Behavior Is Correct

Imagine the legacy system does this:

Customer age 65 → no discount
Customer age 66 → discount

The new system does:

Customer age 65 → discount
Customer age 66 → discount

AI may look at the code and say:

The new implementation appears more logical because senior discounts typically begin at age 65.

That's irrelevant.

The business rule might be:

age > 65

for a reason. Or the legacy behavior might contain a bug.

You need evidence.

Use:

requirements
existing tests
production behavior
business owners
historical tickets
commit history
contracts

AI can help gather and summarize that evidence. It shouldn't invent the rule.

Differential testing is valuable because it tells you that there's a difference before you accidentally turn that difference into production behavior.

How to Use Shadow Traffic Safely

Once offline differential tests look good, you can sometimes compare behavior with real traffic. This is often called shadowing or traffic mirroring.

The pattern looks like:

real request
    │
    ├────────────→ legacy system
    │                  │
    │                  ↓
    │             real response
    │
    └────────────→ new system
                       │
                       ↓
                  shadow result

The user still receives:

legacy response

while the new system processes a copy of the request.

Then you compare:

legacy output
vs.
shadow output

This can reveal cases that your test suite never captured.

For example:

unexpected null combinations
rare customer states
unusual international data
old records
large values
unusual sequence patterns

But shadow execution requires careful design, especially when the operation has side effects.

How to Prevent Shadow Execution from Duplicating Side Effects

Imagine shadowing:

POST /payments

If both systems really execute the payment, you have a serious problem.

The same applies to:

send email
create shipment
charge card
modify inventory
publish event
write external record

The shadow implementation shouldn't perform destructive or externally visible effects unless they're safely isolated.

One approach is to replace real gateways with recording adapters:

class ShadowPaymentGateway
  implements PaymentGateway {
  calls: PaymentRequest[] = [];

  async charge(
    request: PaymentRequest
  ) {
    this.calls.push(request);

    return {
      paymentId: "shadow",
    };
  }
}

The new implementation still tries to execute:

payment

but instead of charging a real card, the shadow adapter records:

what would have been sent

You can then compare that intent with the legacy side effect.

This distinction is important:

compare behavior

does not mean:

duplicate production effects

Measure Divergence Instead of Waiting for Perfection

When running thousands of comparisons, a binary:

pass / fail

may not tell the whole story.

You can measure divergence.

For example:

Requests compared:     100,000
Equivalent:             99,620
Different:                 380

Divergence rate:          0.38%

Then classify those 380:

250 timestamp differences
80 known intentional changes
30 comparator problems
15 migration defects fixed
5 still unexplained

After normalization:

meaningful unresolved divergence:
5 / 100,000
= 0.005%

Now the conversation becomes much more concrete.

Instead of:

I think the migration is ready.

you can say:

We compared 100,000 representative executions and have five unresolved behavioral differences.

Whether that's acceptable depends on what those five cases are.

One incorrect financial transaction can matter more than 100 harmless formatting differences.

So don't evaluate only the percentage. Evaluate the severity.

How to Know When You're Ready for Cutover

Differential testing doesn't give you a universal threshold. But it can give you evidence.

Before cutover, I would want to answer questions such as:

Have Important Input Classes Been Compared?

Not only happy paths.

Include:

boundaries
errors
historical bugs
large values
missing values
rare states

Are Meaningful Differences Classified?

Avoid:

we have 47 unexplained mismatches

Are Critical Differences Resolved?

Especially:

money
authorization
state transitions
data integrity
external contracts
idempotency

Are Intentional Differences Documented?

If the new behavior intentionally differs, that should be explicit.

Are Side Effects Equivalent?

Not only responses.

Have Production-like Cases Been Tested?

Synthetic fixtures alone may not be enough.

Can the Migration Be Rolled Back?

Differential confidence reduces risk. It doesn't eliminate the need for rollback.

If you can answer these questions, you're much closer to a controlled cutover.

A Practical Differential Testing Workflow

Here's the workflow I would use.

1. Pick One Capability

For example:

Process Order
Calculate Invoice
Approve Customer

Don't compare the whole platform at once.

2. Define the Observable Contract

List what matters:

return value
status
error
database state
events
external calls

3. Create Legacy and New Adapters

Expose both implementations through the same conceptual interface.

4. Define Normalization Rules

Decide how to handle:

timestamps
generated IDs
ordering
representation changes
optional values

Do this before looking at lots of failures. Otherwise you may weaken the comparator simply to make results pass.

5. Compare Known Cases

Begin with:

existing tests
characterization cases
edge cases
historical bugs

6. Capture Side Effects

Use recording or fake adapters where necessary.

7. Automate the Harness

Produce structured output for every mismatch.

For example:

{
  "caseId": "case-493",
  "equivalent": false,
  "legacy": {},
  "migrated": {},
  "difference": {}
}

8. Classify Differences

Use categories:

defect
intentional change
normalization issue
nondeterminism
unknown

9. Add Representative Real-World Cases

Use anonymized or safely reconstructed production patterns.

10. Shadow Real Traffic When Appropriate

Only after controlling side effects and privacy risk.

11. Measure Divergence

Track both:

frequency
severity

12. Resolve Unknowns Before Cutover

The most dangerous category is often not:

different

It is:

different and nobody knows why

What Differential Testing Can't Prove

Differential testing has an important limitation: it compares the new system against the old one.

That means the legacy system becomes a behavioral reference. But the legacy system may already be wrong.

Suppose:

legacy output = wrong
new output    = same wrong result

The differential test passes, but that doesn't make the behavior correct.

This is why differential testing should complement:

specification tests
characterization tests
business requirements
security testing
performance testing
contract testing
domain review

It answers:

Did behavior change?

It doesn't automatically answer:

Is this the right behavior?

That distinction matters. The legacy application is evidence, it's not absolute truth.

Differential Testing Turns Migration Risk into Evidence

There's another reason I like this technique. Without differential testing, migration discussions can become subjective.

One person says:

The new implementation looks ready.

Another says:

I do not trust it yet.

Both may have reasonable instincts, but neither statement is very measurable.

Differential testing changes the conversation.

Now you can say:

12,000 cases compared
47 differences found
31 representation differences
9 intentional behavior changes
6 migration defects fixed
1 unresolved

That is a much better engineering discussion. You're converting uncertainty into observable differences. Then you can decide what to do with them.

Conclusion

A legacy migration is not complete because the new implementation passes its own tests.

The harder question is whether it preserves the behavior that matters from the system it is replacing.

Differential testing gives you another way to answer that question.

Run both implementations with the same inputs.

Compare outputs.

Compare errors.

Compare side effects.

Normalize only the differences that truly do not matter.

Investigate everything else.

And when possible, use representative production behavior to discover cases your test suite did not anticipate.

The migration sequence now becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate
↓
Compare
↓
Cut over

AI can accelerate this process too.

It can help build comparators, analyze failures, group similar divergences, inspect code paths, and suggest additional test cases.

But it should not decide which implementation is correct.

That still requires evidence, domain knowledge, and engineering judgment.

The purpose of differential testing is not to eliminate uncertainty completely.

It is to make uncertainty visible before you switch production traffic.

Because during a migration, discovering that the new system behaves differently is useful.

Discovering it after the old system has been turned off is much more expensive.

]]> <![CDATA[ How to Refactor a Legacy Application Before Migrating It ]]> https://www.freecodecamp.org/news/refactor-legacy-application-before-migration/ 6a9f3503813f6309fdfcd6e3 Mon, 07 Sep 2026 22:04:51 +0000 The moment a team decides to migrate a legacy application, there's usually pressure to start moving code.

Move the database, the API, or the UI. Move the application to a new framework, runtime, cloud provider, or architecture.

That sounds reasonable, but there's a problem.

If the current system mixes business rules, persistence, infrastructure, external integrations, and orchestration inside the same modules, migration becomes much harder than it needs to be.

You're not just moving software. You're trying to move several responsibilities that have become entangled over years of development.

This is why I often prefer to refactor before migrating. Not to make the legacy system beautiful or redesign everything. And definitely not to turn the preparation phase into another rewrite.

The goal is much narrower: change the structure enough that important behavior can move independently.

In the previous steps of this workflow, we first tried to understand the codebase and then used characterization tests to protect the behavior we were about to change.

Now you'll learn how you can start changing the structure.

In this tutorial, I'll show you how to prepare a legacy application for migration by:

  • choosing a migration boundary,

  • separating business rules from infrastructure,

  • introducing seams,

  • isolating side effects,

  • creating adapters around external systems,

  • reducing dependency direction problems,

  • extracting cohesive application behavior,

  • using characterization tests throughout the refactor,

  • using AI without letting it redesign the system blindly,

  • and knowing when the application is ready to start migrating.

The examples use TypeScript, but the process applies to most languages and architectures.

The objective is not:

legacy application
↓
perfect architecture

Instead, it's:

legacy application
↓
migration-friendly structure
↓
incremental migration

That difference can save a lot of unnecessary work.

Prerequisites

You should be comfortable with:

  • reading an existing codebase

  • TypeScript or a similar language

  • unit and integration testing

  • dependency injection

  • interfaces and adapters

  • basic software architecture

  • incremental refactoring

You should also have some behavioral protection around the capability you plan to modify.

That may include:

  • characterization tests

  • integration tests

  • contract tests

or another reliable way to verify existing behavior.

Refactoring without that protection is possible. But it's also much harder to distinguish a structural improvement from an accidental behavioral change.

Table of Contents

Why Migration Problems Often Start Before the Migration

Imagine you need to migrate an order-processing application.

You inspect the main service and find something like this:

async function processOrder(orderId: string) {
  const connection = await mysql.getConnection();

  const [rows] = await connection.query(
    "SELECT * FROM orders WHERE id = ?",
    [orderId]
  );

  const order = rows[0];

  if (!order) {
    throw new Error("Order not found");
  }

  if (order.customer_type === "PREMIUM") {
    order.total = order.total * 0.9;
  }

  if (
    order.country === "AR" &&
    order.payment_method === "TRANSFER"
  ) {
    order.total -= 500;
  }

  await connection.query(
    "UPDATE orders SET total = ?, status = ? WHERE id = ?",
    [order.total, "PROCESSED", order.id]
  );

  await paymentProvider.createPayment({
    orderId: order.id,
    amount: order.total,
  });

  await eventBus.publish("order.processed", {
    id: order.id,
    total: order.total,
  });

  await emailClient.send({
    to: order.customer_email,
    template: "order-processed",
  });

  return order;
}

Suppose the migration goal is:

MySQL       → PostgreSQL
Old runtime → New runtime
Legacy API  → New service

The obvious temptation is to begin translating this function into the target stack.

But what exactly are you migrating?

The function contains:

database access
business rules
state transition
payment integration
event publication
email delivery
application orchestration

Changing the database now risks affecting pricing, while changing the payment client risks affecting persistence. And moving the function into another service means moving all of its dependencies at once.

The migration difficulty is partly caused by the current structure. So before migrating, you'll want to create enough separation that those concerns can move independently.

Choose a Migration Boundary Before Refactoring

Don't begin with:

Let's clean up the application.

Begin with:

What do we want to migrate first?

Suppose you decide the first capability will be Process Order. That gives your refactor a boundary.

Now you can map:

Input:
orderId

Business behavior:
load order
calculate adjustments
mark as processed

Side effects:
persist order
create payment
publish event
send email

Output:
processed order

This is much more useful than deciding to refactor:

src/services/

because a folder isn't necessarily a business boundary.

Migration works better when you can reason about capabilities.

For example:

Process Order
Cancel Order
Generate Invoice
Register Customer
Renew Subscription

Each can potentially become a migration unit.

Don't Refactor the Entire Application

Once you start identifying architectural problems, it becomes tempting to fix all of them.

You may notice:

circular dependencies
duplicated repositories
global configuration
large services
static helpers
direct database access
inconsistent error handling
mixed domain models

All of those may deserve attention, but the migration doesn't require all technical debt to disappear.

Suppose your target is the order-processing capability. A useful rule is to refactor only what prevents this capability from moving safely.

For example:

Problem:
Order processing calls MySQL directly.

Relevant?
Yes.

Problem:
The reporting module uses inconsistent date formatting.

Relevant?
Probably not.

Problem:
Order processing calls the payment SDK directly.

Relevant?
Yes.

Problem:
The admin UI contains duplicated CSS.

Relevant?
No.

This prevents preparation from becoming an open-ended cleanup project.

Legacy modernization needs scope discipline.

Separate Business Rules from Infrastructure

The most valuable structural change is often separating business behavior from technology-specific details.

Take this code:

async function processOrder(orderId: string) {
  const order = await mysqlOrders.find(orderId);

  if (order.customerType === "PREMIUM") {
    order.total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    order.total -= 500;
  }

  await mysqlOrders.update(order);

  await stripe.createPayment({
    orderId: order.id,
    amount: order.total,
  });
}

The pricing behavior itself doesn't need MySQL or Stripe.

You can extract it:

type Order = {
  id: string;
  total: number;
  customerType: "STANDARD" | "PREMIUM";
  country: string;
  paymentMethod: "CARD" | "TRANSFER";
};

function calculateOrderTotal(order: Order): number {
  let total = order.total;

  if (order.customerType === "PREMIUM") {
    total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    total -= 500;
  }

  return Math.max(total, 0);
}

Now:

pricing behavior

is no longer coupled to:

MySQL
Stripe

This doesn't require a complete domain-driven redesign. It's simply a useful separation.

The next migration step can replace infrastructure while leaving this behavior unchanged.

Introduce Seams Around Hard Dependencies

Legacy code often contains dependencies that can't easily be replaced in tests or migration code.

For example:

class OrderService {
  async process(orderId: string) {
    const client = new LegacyDatabaseClient();

    const order = await client.findOrder(orderId);

    // ...
  }
}

The database dependency is created inside the method.

That makes substitution difficult.

A small preparatory refactor can introduce a seam:

interface OrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

Then:

class OrderService {
  constructor(
    private readonly orders: OrderRepository
  ) {}

  async process(orderId: string) {
    const order = await this.orders.findById(orderId);

    if (!order) {
      throw new Error("Order not found");
    }

    // existing behavior
  }
}

Now the existing MySQL implementation can satisfy the interface:

class MySqlOrderRepository implements OrderRepository {
  async findById(id: string) {
    // existing MySQL behavior
  }

  async save(order: Order) {
    // existing MySQL behavior
  }
}

Later, the migration can introduce:

class PostgresOrderRepository implements OrderRepository {
  // new implementation
}

Notice what we didn't change: we didn't change the business behavior. We changed the replaceability of a dependency.

That's exactly the kind of refactoring that helps migration.

Isolate Side Effects from Decision Logic

Another useful separation is between:

deciding

and:

performing

Suppose cancellation currently looks like this:

async function cancelOrder(order: Order) {
  if (order.status === "SHIPPED") {
    throw new Error("Cannot cancel shipped order");
  }

  order.status = "CANCELLED";

  await orders.save(order);
  await inventory.release(order.id);
  await payment.refund(order.id);
  await audit.log("ORDER_CANCELLED", order.id);
}

There are two different responsibilities here.

The business decision:

Can this order be cancelled?
What should its new state be?

And the operational effects:

persist
release inventory
refund
audit

You could first extract the decision:

function cancelOrderState(order: Order): Order {
  if (order.status === "SHIPPED") {
    throw new Error("Cannot cancel shipped order");
  }

  return {
    ...order,
    status: "CANCELLED",
  };
}

Then orchestration remains:

async function cancelOrder(order: Order) {
  const cancelled = cancelOrderState(order);

  await orders.save(cancelled);
  await inventory.release(cancelled.id);
  await payment.refund(cancelled.id);
  await audit.log("ORDER_CANCELLED", cancelled.id);

  return cancelled;
}

The behavior is still the same, but now the state transition can be tested and migrated independently.

That matters if the target architecture changes how side effects are executed.

For example, the future version might use:

transactional outbox
event-driven workflow
queue
workflow engine

You don't need to introduce those mechanisms yet. You only need to stop the current decision logic from depending directly on them.

Put External Systems Behind Adapters

External SDKs often leak deeply into legacy code.

For example:

const result = await stripe.paymentIntents.create({
  amount: order.total,
  currency: "usd",
  metadata: {
    orderId: order.id,
  },
});

If dozens of application modules depend directly on the Stripe SDK, replacing or relocating payment processing becomes difficult.

Create an application-level boundary instead:

type PaymentRequest = {
  orderId: string;
  amount: number;
};

type PaymentResult = {
  paymentId: string;
};

interface PaymentGateway {
  charge(
    request: PaymentRequest
  ): Promise<PaymentResult>;
}

The Stripe adapter contains the provider-specific details:

class StripePaymentGateway implements PaymentGateway {
  async charge(
    request: PaymentRequest
  ): Promise<PaymentResult> {
    const result =
      await stripe.paymentIntents.create({
        amount: request.amount,
        currency: "usd",
        metadata: {
          orderId: request.orderId,
        },
      });

    return {
      paymentId: result.id,
    };
  }
}

The application now knows about:

PaymentGateway

instead of:

Stripe SDK

This is useful for migration because provider-specific code is localized.

The same pattern works for:

email providers
message brokers
cloud storage
ERP integrations
CRM APIs
identity providers
search engines

The adapter isn't valuable because interfaces are fashionable. It's valuable because it creates a boundary you can move.

Improve Dependency Direction Without Rebuilding Everything

Legacy systems often have dependency relationships such as:

business logic
    ↓
database SDK
    ↓
framework utilities

That makes infrastructure difficult to replace.

You don't necessarily need to implement full Clean Architecture. You only need to improve dependency direction where migration requires it.

For example:

Before:

OrderService
   ↓
MySQL

After:

OrderService
   ↓
OrderRepository
   ↑
MySqlOrderRepository

The application depends on an abstraction. The infrastructure implements it.

The same can happen with payments:

OrderService
   ↓
PaymentGateway
   ↑
StripePaymentGateway

and messaging:

OrderService
   ↓
OrderEvents
   ↑
KafkaOrderEvents

Now replacing infrastructure no longer requires rewriting the application service. That's the important outcome.

Extract a Cohesive Application Boundary

After several small refactors, the capability may start to look like this:

interface OrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

interface PaymentGateway {
  charge(request: {
    orderId: string;
    amount: number;
  }): Promise<void>;
}

interface OrderEvents {
  processed(order: Order): Promise<void>;
}

class ProcessOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly payments: PaymentGateway,
    private readonly events: OrderEvents
  ) {}

  async execute(orderId: string) {
    const order = await this.orders.findById(orderId);

    if (!order) {
      throw new Error("Order not found");
    }

    const total = calculateOrderTotal(order);

    const processed: Order = {
      ...order,
      total,
      status: "PROCESSED",
    };

    await this.orders.save(processed);

    await this.payments.charge({
      orderId: processed.id,
      amount: processed.total,
    });

    await this.events.processed(processed);

    return processed;
  }
}

This isn't necessarily the final architecture. That's important.

We aren't claiming:

This is how the application should look forever.

We're just saying:

This capability now has boundaries that make migration easier.

The infrastructure can change independently.

The business rules are testable. The orchestration is visible. And the external contracts are explicit.

That's enough to start considering migration.

Keep Behavioral Tests Running During the Refactor

This is where the characterization tests from the previous step become useful.

Suppose the original behavior was protected with:

it("preserves premium order processing behavior", async () => {
  const result = await processOrder("order-1");

  expect(result.total).toBe(9000);
  expect(result.status).toBe("PROCESSED");

  expect(payment.charge).toHaveBeenCalledWith({
    orderId: "order-1",
    amount: 9000,
  });

  expect(events.processed).toHaveBeenCalled();
});

Now you can change:

direct database access

into:

repository

and run the test.

Then change:

direct payment SDK

into:

payment adapter

and run the test.

Then extract:

pricing logic

and run the test.

The rhythm becomes:

small structural change
↓
test
↓
small structural change
↓
test
↓
small structural change
↓
test

This matters because structural refactoring is much easier to reason about when behavioral changes aren't happening at the same time.

If a test fails after one small change, the possible cause is narrow.

If a test fails after a two-week rewrite, the possible cause is almost everything.

How to Use AI During Structural Refactoring

AI can help a lot during this phase.

But the useful prompts are different from:

Refactor this application using Clean Architecture.

Instead, give the model a constrained transformation.

For example:

This service currently accesses MySQL directly.

I want to introduce an OrderRepository seam without
changing observable behavior.

Tasks:

1. identify every database operation used by this service,
2. propose the smallest repository interface needed,
3. move existing database calls behind an adapter,
4. preserve return values, errors, and call order where relevant,
5. do not change business rules,
6. do not introduce additional abstractions.

Explain every structural change before generating code.

That gives AI a much narrower job.

Another useful request is:

Compare the implementation before and after this refactor.

Identify any observable behavior that may have changed.

Check specifically:

- exceptions,
- return values,
- side effects,
- ordering of side effects,
- null handling,
- transaction boundaries,
- retry behavior.

Do not assume equivalence because the code looks similar.

This is where AI can be valuable as a second reviewer.

It can inspect differences faster than you can manually scan large changes. But the tests still provide stronger evidence.

Don't Ask AI to Design the Target Architecture Too Early

AI is very good at recognizing common architecture patterns. But that can also be dangerous.

Give a model a large legacy service and ask:

How should this be modernized?

and you may receive:

microservices
event-driven architecture
CQRS
repository pattern
domain events
message broker
API gateway
distributed cache

All of those are legitimate technologies or patterns, but none of them are automatically justified.

Before choosing a target architecture, you need constraints.

For example:

deployment frequency
team size
transactional requirements
latency
failure tolerance
data ownership
integration boundaries
operational maturity
traffic
cost
regulatory requirements

A monolith with good boundaries may be a better target than microservices. A synchronous workflow may be better than event-driven processing. And a database migration may not require changing the domain model.

Architecture should follow constraints, not pattern recognition.

Use AI to evaluate options. Don't let the presence of a familiar pattern become the reason to adopt it.

How to Know When a Capability Is Ready to Migrate

At some point, you have to stop refactoring. And that decision matters.

You don't need perfect code. A capability is usually much closer to migration-ready when you can answer these questions clearly.

Can I Describe its Inputs?

For example:

orderId
customer
request payload
event

Can I Describe its Outputs?

For example:

processed order
HTTP response
event
database change

Are its Important Business Rules Visible?

They don't have to be perfect, but you should know where they live.

Are External Dependencies Explicit?

For example:

OrderRepository
PaymentGateway
OrderEvents
EmailSender

Can Infrastructure Be Substituted?

If replacing MySQL requires changing pricing logic, the boundary is probably not ready.

Are Important Behaviors Protected?

You should have enough tests to detect accidental changes.

Do You Know the Side Effects?

For example:

persist order
create payment
publish event
send email

Are Major Unknowns Documented?

Some uncertainty may remain. But it shouldn't be invisible.

If you can answer those questions, you probably have enough structure to begin migrating that capability.

A Practical Pre-Migration Refactoring Workflow

Here's the workflow I would use.

1. Choose One Capability

Don't refactor the whole application.

Pick:

Process Order
Generate Invoice
Renew Subscription

2. Confirm Behavioral Protection

Before structural changes, make sure critical behavior has tests.

Capture:

outputs
state transitions
side effects
errors
contracts

3. Identify Migration Blockers

Look for coupling such as:

direct database access
provider SDKs
global state
framework-specific objects
static dependencies
shared mutable state

4. Extract Pure Business Logic Where Possible

Move calculations and decisions away from infrastructure.

For example:

calculate price
validate transition
choose status
calculate commission

5. Introduce Seams

Create minimal boundaries around:

database
payments
events
email
storage
external APIs

Don't create abstractions without a migration reason.

6. Localize Infrastructure

Move technology-specific behavior into adapters.

For example:

MySqlOrderRepository
StripePaymentGateway
KafkaOrderEvents
SendGridEmailSender

7. Make Orchestration Visible

Aim for a capability where the sequence is understandable:

load
↓
decide
↓
persist
↓
perform side effects
↓
return

8. Run Behavioral Tests After Every Step

Don't batch ten refactors together. Keep the changes small.

9. Compare Before and After

Check:

inputs
outputs
errors
side effects
data shapes
ordering
transactions

10. Stop When Migration Becomes Possible

Don't continue refactoring because the code could still be cleaner. It always could.

The objective is migration readiness.

What Not to Refactor Before Migration

There are several things I would usually avoid changing during this phase unless they directly block migration.

Naming Everywhere

You may dislike hundreds of old names. But renaming everything produces large diffs with little migration value.

Formatting the Entire Repository

Same problem. Noise makes behavioral changes harder to review.

Replacing Every Pattern

A legacy system may contain:

singletons
service locators
static utilities
large classes

Some may remain temporarily. Fix the ones crossing your migration boundary.

Rewriting Stable Algorithms

If an old calculation is ugly but protected and isolated, it may be safer to move it first and improve it later.

Fixing Every Discovered Bug

This one is especially important.

If you discover a bug while preparing a migration, record it. Then decide whether fixing it belongs in the same change.

Mixing:

structural refactor
+
behavioral correction
+
platform migration

makes failures much harder to understand.

Sometimes the right answer is:

preserve bug
migrate
fix bug intentionally afterward

That sounds uncomfortable. But accidental behavior changes during migration can be much more dangerous.

Refactoring Is Preparation, Not the Migration

It's easy for pre-migration refactoring to become an endless architecture project.

You start with:

We need to isolate the database.

Then:

We should redesign the domain model.

Then:

Maybe we should introduce events.

Then:

If we're doing that, maybe this should become a microservice.

Months later, nothing has migrated. The refactor has become the project.

That's a failure mode, too. The objective should remain concrete.

Before:

ProcessOrder
├── MySQL
├── pricing rules
├── Stripe
├── Kafka
├── email
└── framework internals

After:

ProcessOrder
├── OrderRepository
├── pricing rules
├── PaymentGateway
├── OrderEvents
└── EmailSender

That may be enough.

Now you have choices.

You can migrate:

MySQL → PostgreSQL

without redesigning pricing.

You can replace:

Stripe adapter

without changing order orchestration.

You can move:

ProcessOrder

into another runtime while preserving its contracts.

The refactor created options. That's the value.

Conclusion

Legacy migrations become risky when several types of change happen at once.

You change:

behavior
architecture
infrastructure
runtime
data
deployment

and then try to understand which change caused the failure.

A safer approach is to reduce that uncertainty before migration begins.

First understand the capability, then characterize its behavior, and then change its structure without intentionally changing what it does.

Create boundaries around dependencies. Separate business decisions from infrastructure. Localize external systems. Keep side effects visible. Run behavioral tests after every structural change. And stop refactoring when the capability becomes movable.

The sequence becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate

AI can make the refactoring phase dramatically faster.

It can identify dependencies, extract interfaces, move calls behind adapters, compare implementations, and review large diffs.

But faster refactoring doesn't remove the need for architectural judgment. It makes that judgment more important.

Because the goal isn't to produce the cleanest version of the legacy system. The goal is to create just enough structure to move it safely.

And once you can change the infrastructure without changing the behavior, migration stops looking like a rewrite.

It starts looking like a sequence of controlled changes.

]]> <![CDATA[ The Design Patterns Handbook: Learn Popular Design Patterns with C# Code Examples ]]> https://www.freecodecamp.org/news/the-design-patterns-handbook-learn-popular-design-patterns-with-c-code-examples/ 6a9eec68a0d0c091f35da7b8 Mon, 07 Sep 2026 16:55:04 +0000 Design patterns are reusable solutions to common problems in software design. Think of them as blueprints: not finished code, but proven templates you can adapt to solve a specific problem in your own codebase.

This handbook serves as a practical guide to understanding software design patterns. I wrote it for every developer, regardless of the language you program in. Examples are written in C#, but every concept here applies equally to Python, Java, TypeScript, Go, and beyond.

The source code lives at github.com/Clifftech123/design-patterns-handbook.

Things to Keep in Mind:

  • Design patterns aren't code. They're a way of thinking about how to structure your code. They're a tool, not a silver bullet, for solving specific design problems.

  • The concepts are universal. The examples here are written in C#, but the same patterns exist in every language. If you write Python, Java, Go, or TypeScript, you're already using some of these without knowing it.

  • There's no one-size-fits-all pattern. Each pattern exists to address a particular kind of problem. Understanding what problem a pattern solves is more important than memorizing the implementation.

I use C# here as the teaching language because it's clear, readable, and widely understood. The goal of this handbook is for you to walk away understanding the pattern itself, not just the C# code.

There are three main types of design patterns: Creational, Structural, and Behavioral. We'll look at each one in turn here, starting with Creational.

What We'll Cover:

Creational Design Patterns

Simply put, Creational patterns are all about how objects are created. They can be divided into class-creation patterns, which use inheritance to decide which class to instantiate, and object-creation patterns, which use delegation to get the job done.

Wikipedia describes them as:

"A creational pattern aims to separate a system from how its objects are created, composed, and represented. They increase the system's flexibility in terms of the what, who, how, and when of object creation."

(Source)

So Creational patterns keep the details of object creation hidden from the client code, making the system easier to manage and maintain.

They also abstract away how objects are created, composed, and represented, so the rest of your code doesn't need to care.

There are five Creational design patterns, which we'll go over one by one below:

  1. Singleton: Ensures a class has only one instance and provides a global point of access to it.

  2. Factory Method: Defines an interface for creating an object, but lets subclasses decide which class to instantiate.

  3. Abstract Factory: Provides an interface for creating families of related or dependent objects without specifying their concrete classes.

  4. Builder: Separates the construction of a complex object from its representation, so the same construction process can produce different results.

  5. Prototype: Creates new objects by cloning an existing instance rather than building one from scratch.

1. Singleton Design Pattern

Real World Example:

Think of the conductor of an orchestra. An orchestra has one conductor. Every musician on stage looks to that same conductor for direction: when to start, when to stop, how fast to play, and how loud to go.

The conductor is the single point of authority that all musicians connect to and take decisions from. You can't have two conductors standing at the front giving different instructions. That would cause chaos. No matter which musician needs guidance, they all reach the same one person.

That's exactly how the Singleton works in code: one instance, shared by everyone who needs it, making decisions from one place.

Problems it solves:

  • What if two musicians get different conductors giving different instructions? The performance falls apart. There must be one conductor that every musician looks to, without exception.

  • How does a musician find the conductor? They don't go searching. There's one well-known place everyone looks, and the same conductor is always there.

  • What stops someone from appointing a second conductor? The orchestra itself controls this. Once a conductor is on the podium, no second one can take it.

In simple terms, there's only one instance of the class, and every part of the system that needs it gets access to that exact same instance (never a new one).

Here's how Wikipedia describes the Singleton pattern:

"In object-oriented programming, the singleton pattern is a software design pattern that restricts the instantiation of a class to a singular instance. The pattern is useful when exactly one object is needed to coordinate actions across a system." (Source)

Programming Example:

We'll model the analogy directly now. The OrchestraConductor is the Singleton: one instance, shared by all musicians, making all decisions.

public class OrchestraConductor
{
    // Step 1: Hold the one instance here
    private static OrchestraConductor _instance;

    // Step 2: Private constructor - nobody outside can do: new OrchestraConductor()
    private OrchestraConductor() { }

    // Step 3: The only way to get the conductor
    public static OrchestraConductor GetInstance()
    {
        if (_instance == null)
        {
            _instance = new OrchestraConductor();
        }

        return _instance;
    }

    // Decisions the conductor makes
    public void Start()                    => Console.WriteLine("Conductor: Begin playing.");
    public void Stop()                     => Console.WriteLine("Conductor: Stop playing.");
    public void SetTempo(string tempo)     => Console.WriteLine($"Conductor: Tempo is now {tempo}.");
}

Now let's see it in action:

// Violinist asks for the conductor
OrchestraConductor violinist = OrchestraConductor.GetInstance();

// Pianist asks for the conductor
OrchestraConductor pianist = OrchestraConductor.GetInstance();

// Are they talking to the same conductor?
Console.WriteLine(object.ReferenceEquals(violinist, pianist)); // True

violinist.SetTempo("Allegro");
pianist.Start();

Output:

True
Conductor: Tempo is now Allegro.
Conductor: Begin playing.

Both musicians got the same conductor. The constructor never ran twice. That is the Singleton pattern.

When to Use the Singleton Pattern

Reach for Singleton when you need one shared resource that the whole application talks to, such as a logger, a configuration manager, or a database connection pool.

It's also a good idea when having more than one instance would cause incorrect behaviour or conflicting state.

And it's helpful when you want a global point of access to an object without passing it around everywhere.

2. The Factory Method

Think of a recruitment agency. A company calls the agency and says "we need a worker." The company doesn't go out and create the worker themselves. They just make the request.

The agency decides which specific person to send: a developer, a designer, or a tester, depending on what the company needs. The company doesn't know or care exactly who is coming. They just know the person will be able to do the job.

That's the Factory Method. Your code asks for an object. The Factory decides which specific type to create and hands it back. You work with it without needing to know exactly what it is under the hood.

Problems it solves:

  • The company shouldn't need to know who they're getting. They just need someone who can do the job. The agency handles the decision of whom to send. The company never has to worry about the details.

  • What if the company needs a different type of worker tomorrow? They call the same agency. The agency decides. The company's process doesn't change, only the agency's decision does.

  • What if a new type of worker needs to be introduced? A new specialist agency is created to handle that. Everything else stays exactly the same.

In simple terms, we define an interface for creating an object, but let subclasses decide which class to instantiate. The factory method lets a class defer instantiation to subclasses.

Wikipedia describes it like this:

"In object-oriented programming, the factory method pattern is a design pattern that uses factory methods to deal with the problem of creating objects without having to specify their exact classes. Factory methods can be specified in an interface and implemented by subclasses, or implemented in a base class and optionally overridden by subclasses." (Source)

Programming Example:

The agency is the factory. The worker types are the products. The company is the client.

// The worker interface - all workers can do a job
public interface IWorker
{
    void DoWork();
}

// The concrete workers
public class Developer : IWorker
{
    public void DoWork() => Console.WriteLine("Developer: Writing code.");
}

public class Designer : IWorker
{
    public void DoWork() => Console.WriteLine("Designer: Creating designs.");
}

// The base agency - declares the factory method
public abstract class RecruitmentAgency
{
    // This is the Factory Method - subclasses decide who to hire
    public abstract IWorker HireWorker();
}

// Concrete agencies - each one decides which worker to send
public class TechAgency : RecruitmentAgency
{
    public override IWorker HireWorker() => new Developer();
}

public class DesignAgency : RecruitmentAgency
{
    public override IWorker HireWorker() => new Designer();
}

Now let's see it in action:

// Company A needs a tech worker
RecruitmentAgency agency = new TechAgency();
IWorker worker = agency.HireWorker();
worker.DoWork();

// Company B needs a design worker
RecruitmentAgency agency2 = new DesignAgency();
IWorker worker2 = agency2.HireWorker();
worker2.DoWork();

Output:

Developer: Writing code.
Designer: Creating designs.

The company never used new Developer() or new Designer() directly. The agency made that decision. That is the Factory Method.

3. The Abstract Factory Design Pattern

Real World Example

Think of a furniture store that sells collections. You walk in and choose a style: Modern or Victorian. Once you choose, everything you get comes from that same collection. The sofa, the chair, and the coffee table all match. The store ensures that you never walk out with a modern sofa paired with a Victorian chair. You don't pick individual pieces and hope they go together. The collection guarantees they will.

That's the Abstract Factory. You choose a family, and the Factory produces every object you need from that same family. Everything it gives you is guaranteed to work together.

Problems it solves:

  • What if a customer mixes furniture from different collections? The room looks inconsistent. The store solves this by grouping everything into collections. You pick one collection and everything comes from it.

  • What if the store wants to introduce a new collection? They create a new collection set. Every existing collection stays untouched. The customer's experience doesn't change, only the options grow.

  • What if different stores carry different collections? Each store is its own factory. A customer walks into any store and follows the same process. The store handles which specific pieces to provide.

In simple terms, you provide an interface for creating families of related objects, without specifying their concrete classes.

Wikipedia describes it like this:

"The abstract factory pattern provides a way to create families of related objects without imposing their concrete classes, by encapsulating a group of individual factories that have a common theme without specifying their concrete classes."

Source: Wikipedia - Abstract factory pattern

Programming Example:

The furniture store is the abstract factory. Modern and Victorian are the concrete factories. Sofa and Chair are the products.

// The product interfaces - every furniture type has a contract
public interface ISofa  { void Describe(); }
public interface IChair { void Describe(); }

// Modern collection
public class ModernSofa : ISofa
{
    public void Describe() => Console.WriteLine("Sofa: Sleek modern design.");
}

public class ModernChair : IChair
{
    public void Describe() => Console.WriteLine("Chair: Minimalist modern style.");
}

// Victorian collection
public class VictorianSofa : ISofa
{
    public void Describe() => Console.WriteLine("Sofa: Ornate Victorian design.");
}

public class VictorianChair : IChair
{
    public void Describe() => Console.WriteLine("Chair: Classic Victorian style.");
}

// The abstract factory - every store can produce a sofa and a chair
public interface IFurnitureFactory
{
    ISofa  CreateSofa();
    IChair CreateChair();
}

// Concrete factories - each one produces its own collection
public class ModernFurnitureFactory : IFurnitureFactory
{
    public ISofa  CreateSofa()  => new ModernSofa();
    public IChair CreateChair() => new ModernChair();
}

public class VictorianFurnitureFactory : IFurnitureFactory
{
    public ISofa  CreateSofa()  => new VictorianSofa();
    public IChair CreateChair() => new VictorianChair();
}

Now let's see it in action:

// Customer orders a Modern collection
IFurnitureFactory factory = new ModernFurnitureFactory();
ISofa  sofa  = factory.CreateSofa();
IChair chair = factory.CreateChair();
sofa.Describe();
chair.Describe();

// Customer orders a Victorian collection
IFurnitureFactory factory2 = new VictorianFurnitureFactory();
ISofa  sofa2  = factory2.CreateSofa();
IChair chair2 = factory2.CreateChair();
sofa2.Describe();
chair2.Describe();

Output:

Sofa: Sleek modern design.
Chair: Minimalist modern style.
Sofa: Ornate Victorian design.
Chair: Classic Victorian style.

Every piece came from the same collection. The client never used new ModernSofa() or new VictorianChair() directly. The factory kept the family together. That's the Abstract Factory.

When to Use Abstract Factory:

Use the Abstract Factory pattern when your system needs to work with multiple families of related objects and you need to ensure they're always used together.

It also works well when you want to swap out an entire family of objects in one place without touching the rest of your code.

And it's a good choice when you want to enforce consistency across related objects, so nothing from one family gets accidentally mixed with another.

4. The Builder Design Pattern

Real World Example

Think of a tailor making a suit. Every customer that walks in goes through the same process: take measurements, choose the fabric, select the lining, pick the buttons, and decide on the lapel style.

The tailor follows those same steps for every order. But the finished suit is completely unique to each customer. A businessman walks out with a sharp formal suit. A wedding guest walks out with something entirely different. Same process, same tailor, but with different result every time.

That's the Builder. The construction process stays the same. What changes are the choices made at each step.

Problems it solves:

  • What if a suit had to be assembled all at once with no steps? You would have to know every detail upfront and get it all right in one go. The tailor breaks it down into steps so each decision is made clearly, one at a time.

  • What if two customers want completely different suits but go through the same tailor? The tailor follows the same process for both. The steps don't change, only the choices within each step.

  • What if a new suit style needs to be introduced? A new set of choices is defined for that style. The tailoring process itself stays untouched.

In simple terms, you separate the construction of a complex object from its representation, so that the same construction process can create different results.

Wikipedia describes it like this:

"The Builder pattern separates the construction of a complex object from its representation so that the same construction process can create different representations." (Source)

Programming Example:

The tailor is the director. The suit is the product. The builder handles the step-by-step construction.

// The product
public class Suit
{
    public string Fabric  { get; set; }
    public string Lining  { get; set; }
    public string Buttons { get; set; }

    public void Describe()
    {
        Console.WriteLine($"Suit: {Fabric} fabric, {Lining} lining, {Buttons} buttons.");
    }
}

// The builder - defines the steps
public interface ISuitBuilder
{
    void SetFabric();
    void SetLining();
    void SetButtons();
    Suit GetSuit();
}

// Business suit builder
public class BusinessSuitBuilder : ISuitBuilder
{
    private Suit _suit = new Suit();

    public void SetFabric()  => _suit.Fabric  = "Dark wool";
    public void SetLining()  => _suit.Lining  = "Silk";
    public void SetButtons() => _suit.Buttons = "Black horn";
    public Suit GetSuit()    => _suit;
}

// Wedding suit builder
public class WeddingSuitBuilder : ISuitBuilder
{
    private Suit _suit = new Suit();

    public void SetFabric()  => _suit.Fabric  = "Ivory linen";
    public void SetLining()  => _suit.Lining  = "Satin";
    public void SetButtons() => _suit.Buttons = "Pearl";
    public Suit GetSuit()    => _suit;
}

// The tailor - the director who runs the process
public class Tailor
{
    public Suit MakeSuit(ISuitBuilder builder)
    {
        builder.SetFabric();
        builder.SetLining();
        builder.SetButtons();
        return builder.GetSuit();
    }
}

Now let's see it in action:

Tailor tailor = new Tailor();

Suit businessSuit = tailor.MakeSuit(new BusinessSuitBuilder());
businessSuit.Describe();

Suit weddingSuit = tailor.MakeSuit(new WeddingSuitBuilder());
weddingSuit.Describe();

Output:

Suit: Dark wool fabric, Silk lining, Black horn buttons.
Suit: Ivory linen fabric, Satin lining, Pearl buttons.

The same tailor, following the same process, creates two completely different suits. That is the Builder.

When to Use the Builder Design Pattern

Use the Builder pattern when an object has many parts or configurations and building it all at once would be confusing.

It's also a good choice when you want the same construction process to produce different results depending on the choices made at each step.

And reach for it when you want to keep the construction logic separate from the object itself, so each can change independently.

5. The Prototype Design Pattern

Real World Example

Imagine you're building a drawing application. Users can create shapes like circles, rectangles, or triangles, each with its own colour, size, and position.

Now imagine the user wants ten red circles of the same size placed across the canvas. Creating each one from scratch means repeating the same setup ten times. What if the shape is complex, with many configured properties? That becomes expensive and repetitive.

The Prototype pattern solves this by letting you take one fully configured shape and clone it. The clone starts as an exact copy. The user then moves it, recolours it, or resizes it independently. The original shape is never touched. This also means new shape types can be added at runtime without the application needing to know about them in advance.

Problems it solves:

  • Creating a new shape from scratch every time is expensive. If a shape has many properties, setting them all up repeatedly wastes resources. Cloning an already configured object is far cheaper.

  • The application shouldn't need to know the exact type of shape it's copying. At runtime, shapes can be added or removed dynamically. The app just calls clone and gets back a ready object, whatever type it happens to be.

  • Modifying a copy should never affect the original. Each cloned shape is fully independent. Changes to the copy stay with the copy.

In simple terms, you can create new objects by copying an existing one. The copy starts identical to the original and can then be changed independently.

Wikipedia describes it like this:

"The Prototype pattern is used when the type of objects to create is determined by a prototypical instance, which is cloned to produce new objects." (Source)

Programming Example:

Every shape knows how to clone itself. The application never calls new Circle() or new Rectangle() directly at runtime. It clones what already exists.

// The prototype interface - every shape must be able to clone itself
public abstract class Shape
{
    public string Colour { get; set; }
    public int    Size   { get; set; }

    public abstract Shape Clone();
    public abstract void  Describe();
}

// Concrete shapes
public class Circle : Shape
{
    public override Shape Clone()    => (Shape)this.MemberwiseClone();
    public override void  Describe() => Console.WriteLine($"Circle  | Colour: {Colour} | Size: {Size}");
}

public class Rectangle : Shape
{
    public override Shape Clone()    => (Shape)this.MemberwiseClone();
    public override void  Describe() => Console.WriteLine($"Rectangle | Colour: {Colour} | Size: {Size}");
}

Now let's see it in action:

// Create one configured circle
Circle original = new Circle { Colour = "Red", Size = 50 };

// Clone it instead of building from scratch
Shape clone1 = original.Clone();
Shape clone2 = original.Clone();

// Modify the clones independently
clone2.Colour = "Blue";

original.Describe();
clone1.Describe();
clone2.Describe();

Output:

Circle  | Colour: Red  | Size: 50
Circle  | Colour: Red  | Size: 50
Circle  | Colour: Blue | Size: 50

clone2 changed to blue. The original stayed red. Each object is fully independent. That's the Prototype.

When to Use the Prototype Design Pattern:

Use Prototype when creating a new object from scratch is expensive or complex and an existing object already has everything configured.

It's also helpful when the application needs to create objects at runtime without knowing their exact type in advance.

And it's great when you need many variations of an object and want to start from a known good state rather than rebuild every time.

Structural Design Patterns

Simply put, structural patterns are all about how classes and objects are composed to form larger structures. They use inheritance and composition to let you build flexible, efficient structures without having to rewrite everything from scratch.

Wikipedia describes them as:

"In software engineering, structural patterns are design patterns that ease the design by identifying a simple way to realize relationships among entities." (Source)

Structural design patterns describe how objects and classes are combined to form larger, more complex structures while keeping those structures flexible and efficient.

They focus on composition over inheritance: how you connect things, not just what things are.

There are seven Structural design patterns:

  1. Adapter: Converts one interface into another that a client expects, letting incompatible interfaces work together.

  2. Bridge: Decouples an abstraction from its implementation so the two can vary independently.

  3. Composite: Composes objects into tree structures to represent part-whole hierarchies, letting clients treat individual objects and compositions uniformly.

  4. Decorator: Attaches additional responsibilities to an object dynamically, as a flexible alternative to subclassing.

  5. Facade: Provides a simplified, unified interface to a complex subsystem.

  6. Flyweight: Uses sharing to efficiently support a large number of fine-grained objects.

  7. Proxy: Provides a surrogate or placeholder for another object to control access to it.

1. The Adapter Design Pattern

Real World Example

Think of a language translator at a business meeting. A British CEO needs to address a Japanese team. The CEO speaks only English. The team speaks only Japanese. A translator sits between them, converting every English sentence into Japanese and delivering it to the team. Both sides keep speaking their own language. Neither the CEO nor the team change anything about how they communicate. The translator makes them compatible.

That's the Adapter. The client speaks one interface, while the other side speaks a different one. The Adapter sits between them and makes both sides work together without either having to change.

Problems it solves:

  • The CEO can't speak Japanese, and the team can't speak English. They're incompatible. The translator adapts one to the other without changing either side.

  • What if the CEO now needs to address a French team? A French translator is brought in. The CEO's process doesn't change. Only the translator changes.

  • What if an existing class has a useful method but the wrong interface? You wrap it in an adapter. The rest of the system talks to the adapter while the existing class stays untouched.

In simple terms, you wrap an existing class with a new interface so the client can use it without any changes to either side.

Wikipedia describes it like this:

"In software engineering, the adapter pattern is a software design pattern (also known as wrapper) that allows the interface of an existing class to be used as another interface. It is often used to make existing classes work with others without modifying their source code." (Source)

Programming Example:

The CEO is the client and the Japanese team member is the adaptee. They're useful, but they speak the wrong interface. The Translator is the adapter.

// What the CEO expects, someone who can receive a message in English
public interface IEnglishSpeaker
{
    void Speak(string message);
}

// The Japanese team member, speaks only Japanese (the adaptee)
public class JapaneseTeamMember
{
    public void SpeakJapanese(string message)
    {
        Console.WriteLine($"Team member (Japanese): {message}");
    }
}

// The Translator, adapts the Japanese speaker to the English interface
public class Translator : IEnglishSpeaker
{
    private readonly JapaneseTeamMember _teamMember;

    public Translator(JapaneseTeamMember teamMember)
    {
        _teamMember = teamMember;
    }

    public void Speak(string message)
    {
        string translated = TranslateToJapanese(message);
        _teamMember.SpeakJapanese(translated);
    }

    private string TranslateToJapanese(string english) => english switch
    {
        "Good morning, team."         => "おはようございます、チームの皆さん。",
        "Please review the proposal." => "提案書を確認してください。",
        _                             => $"[Japanese: {english}]"
    };
}

// The CEO, only knows how to talk to an IEnglishSpeaker
public class CEO
{
    private readonly IEnglishSpeaker _speaker;

    public CEO(IEnglishSpeaker speaker)
    {
        _speaker = speaker;
    }

    public void Address(string message)
    {
        Console.WriteLine($"CEO (English): {message}");
        _speaker.Speak(message);
    }
}

Now let's see it in action:

JapaneseTeamMember teamMember = new JapaneseTeamMember();
IEnglishSpeaker translator    = new Translator(teamMember);
CEO ceo = new CEO(translator);

ceo.Address("Good morning, team.");
ceo.Address("Please review the proposal.");

Output:

CEO (English): Good morning, team.
Team member (Japanese): おはようございます、チームの皆さん。
CEO (English): Please review the proposal.
Team member (Japanese): 提案書を確認してください。

The CEO never knew about JapaneseTeamMember. The team never knew about the CEO's interface. The Translator made both sides work together without touching either. That's the Adapter.

When to Use it

Use Adapter when you want to use an existing class but its interface doesn't match what your code expects.

It's also helpful when you want to create a reusable class that cooperates with classes that don't have compatible interfaces.

And reach for it when you need to integrate a third-party library or legacy code without modifying it.

2. The Bridge Design Pattern

Real World Example

Think of a TV remote control and a television. The remote is one thing and the TV is another. You can have a basic remote or a smart remote. You can have a Sony TV or a Samsung TV. Any remote works with any TV you're not locked in. Buy a new Samsung TV, and your old remote still works. Buy a smart universal remote, and it works with every TV you own. Neither side needs to know the inner details of the other.

That's the Bridge. The abstraction (remote) and the implementation (TV) are two separate hierarchies that can grow and change completely independently of each other.

Problems it solves:

  • What if every remote was hardwired to one specific TV brand? You would need a SonyBasicRemote, a SamsungBasicRemote, a SonySmartRemote, a SamsungSmartRemote...and so on. One class for every combination. Adding one new TV brand would double your remote classes. The Bridge stops this explosion.

  • What if you want to add a new remote type without touching the TVs? With Bridge, you just create a new remote class. The TVs are untouched.

  • What if you want to add a new TV brand without touching the remotes? Same answer. You add a new TV class. Every existing remote already works with it.

In simple terms, you split a large class into two separate hierarchies (the abstraction and the implementation) so each can be changed and extended without affecting the other.

Wikipedia describes it like this:

"The bridge pattern is a design pattern used in software engineering that is meant to decouple an abstraction from its implementation so that the two can vary independently." (Source)

Programming Example:

The remote control is the abstraction and the TV brand is the implementation. They're connected through a bridge (the ITV interface), but neither hierarchy depends on the other's details.

// The implementation interface — what any TV must be able to do
public interface ITV
{
    void TurnOn();
    void TurnOff();
    void SetChannel(int channel);
    void SetVolume(int volume);
}

// Concrete implementations — each brand handles things its own way
public class SonyTV : ITV
{
    public void TurnOn()           => Console.WriteLine("Sony TV: Powering on. BRAVIA display ready.");
    public void TurnOff()          => Console.WriteLine("Sony TV: Shutting down.");
    public void SetChannel(int ch) => Console.WriteLine($"Sony TV: Switching to channel {ch}.");
    public void SetVolume(int vol) => Console.WriteLine($"Sony TV: Volume set to {vol}.");
}

public class SamsungTV : ITV
{
    public void TurnOn()           => Console.WriteLine("Samsung TV: Turning on. Smart Hub loading.");
    public void TurnOff()          => Console.WriteLine("Samsung TV: Powering off.");
    public void SetChannel(int ch) => Console.WriteLine($"Samsung TV: Channel {ch} selected.");
    public void SetVolume(int vol) => Console.WriteLine($"Samsung TV: Volume at {vol}.");
}

// The abstraction — the remote holds a reference to whichever TV it controls
public abstract class RemoteControl
{
    protected ITV _tv;

    protected RemoteControl(ITV tv) { _tv = tv; }

    public abstract void TurnOn();
    public abstract void TurnOff();
    public abstract void SetChannel(int channel);
}

// Refined abstraction — a basic remote, does exactly what the TV does
public class BasicRemote : RemoteControl
{
    public BasicRemote(ITV tv) : base(tv) { }

    public override void TurnOn()           => _tv.TurnOn();
    public override void TurnOff()          => _tv.TurnOff();
    public override void SetChannel(int ch) => _tv.SetChannel(ch);
}

// Refined abstraction — a smart remote, adds its own behaviour on top
public class SmartRemote : RemoteControl
{
    public SmartRemote(ITV tv) : base(tv) { }

    public override void TurnOn()
    {
        Console.WriteLine("Smart Remote: Activating voice control.");
        _tv.TurnOn();
    }

    public override void TurnOff()
    {
        Console.WriteLine("Smart Remote: Saving watch history.");
        _tv.TurnOff();
    }

    public override void SetChannel(int ch)
    {
        Console.WriteLine("Smart Remote: Looking up channel guide.");
        _tv.SetChannel(ch);
    }

    public void SetVolume(int vol) => _tv.SetVolume(vol);
}

Now let's see it in action:

// Basic remote paired with a Sony TV
Console.WriteLine("--- Basic Remote + Sony TV ---");
RemoteControl basicSony = new BasicRemote(new SonyTV());
basicSony.TurnOn();
basicSony.SetChannel(5);
basicSony.TurnOff();

// Smart remote paired with a Samsung TV
Console.WriteLine("\n--- Smart Remote + Samsung TV ---");
SmartRemote smartSamsung = new SmartRemote(new SamsungTV());
smartSamsung.TurnOn();
smartSamsung.SetChannel(10);
smartSamsung.SetVolume(20);
smartSamsung.TurnOff();

// Swap freely — smart remote now with Sony, no code changes needed
Console.WriteLine("\n--- Smart Remote + Sony TV ---");
SmartRemote smartSony = new SmartRemote(new SonyTV());
smartSony.TurnOn();
smartSony.SetChannel(3);
smartSony.TurnOff();

Output:

--- Basic Remote + Sony TV ---
Sony TV: Powering on. BRAVIA display ready.
Sony TV: Switching to channel 5.
Sony TV: Shutting down.

--- Smart Remote + Samsung TV ---
Smart Remote: Activating voice control.
Samsung TV: Turning on. Smart Hub loading.
Smart Remote: Looking up channel guide.
Samsung TV: Channel 10 selected.
Samsung TV: Volume at 20.
Smart Remote: Saving watch history.
Samsung TV: Powering off.

--- Smart Remote + Sony TV ---
Smart Remote: Activating voice control.
Sony TV: Powering on. BRAVIA display ready.
Smart Remote: Looking up channel guide.
Sony TV: Switching to channel 3.
Smart Remote: Saving watch history.
Sony TV: Shutting down.

The same SmartRemote worked with both Sony and Samsung without any changes. Adding a new TV brand like LG means creating one new class, and every existing remote works with it immediately. That's the Bridge.

When to Use it

Use the Bridge pattern when you want to avoid a permanent binding between an abstraction and its implementation, so either can be swapped at runtime.

You can also use it when both the abstraction and the implementation should be independently extensible through subclassing.

And it's a good fit when changes to the implementation should have no impact on the client code. The client shouldn't need to be recompiled.

3. The Composite Design Pattern

Real World Example

Think of a company organisation chart. A company has a CEO. Under the CEO are department heads, each leading a department full of employees. Under some departments are even smaller sub-teams.

Now imagine you want to know the total salary cost. You can ask a single employee they tell you their salary. You can ask a whole department, which adds up every person inside it, including nested teams. Or you can ask the entire company: it rolls up every salary across every level.

The same question, asked the same way, whether you're talking to one person or thousands.

That's the Composite pattern. Individual items and groups of items share the same interface. The caller never needs to know which one they're dealing with.

Problems it solves:

  • What if you had to write different code to handle a single employee versus a whole department? You would end up with if checks everywhere just to figure out what you're talking to. Composite removes that entirely: one interface, always.

  • What if departments can contain other departments? Composite handles any depth of nesting naturally. The caller just asks the top of the tree and the operation flows down automatically.

  • What if you want to add a new type of team or role? You implement the same interface. Everything above it in the tree keeps working without any changes.

In simple terms, you compose objects into tree structures. This lets individual objects and groups of objects be treated through the same interface, so the caller never has to care about the difference.

Wikipedia describes it like this:

"The composite pattern describes a group of objects that are treated the same way as a single instance of the same type of object. The intent of a composite is to compose objects into tree structures to represent part-whole hierarchies." (Source)

Programming Example:

Every node in the tree (whether a single employee or an entire department) implements IEmployee. The caller treats them identically.

// The component interface — every leaf and composite shares this contract
public interface IEmployee
{
    string Name    { get; }
    int    GetSalary();
    void   GetDetails(string indent = "");
}

// The leaf — a single employee with no reports
public class Employee : IEmployee
{
    private readonly int _salary;

    public string Name { get; }

    public Employee(string name, int salary)
    {
        Name    = name;
        _salary = salary;
    }

    public int  GetSalary()                    => _salary;
    public void GetDetails(string indent = "") => Console.WriteLine($"{indent}- {Name} (£{_salary:N0})");
}

// The composite — a department that holds employees or other departments
public class Department : IEmployee
{
    private readonly List<IEmployee> _members = new();

    public string Name { get; }

    public Department(string name) { Name = name; }

    public void Add(IEmployee employee)    => _members.Add(employee);
    public void Remove(IEmployee employee) => _members.Remove(employee);

    public int GetSalary() => _members.Sum(m => m.GetSalary());

    public void GetDetails(string indent = "")
    {
        Console.WriteLine($"{indent}[{Name}] Total: £{GetSalary():N0}");
        foreach (var member in _members)
            member.GetDetails(indent + "  ");
    }
}

Now let's see it in action:

// Individual employees
var ceo        = new Employee("Alice (CEO)",        120_000);
var cto        = new Employee("Bob (CTO)",           95_000);
var dev1       = new Employee("Carol (Developer)",   65_000);
var dev2       = new Employee("David (Developer)",   62_000);
var cfo        = new Employee("Eve (CFO)",           90_000);
var accountant = new Employee("Frank (Accountant)",  55_000);

// Build the Engineering department
var engineering = new Department("Engineering");
engineering.Add(cto);
engineering.Add(dev1);
engineering.Add(dev2);

// Build the Finance department
var finance = new Department("Finance");
finance.Add(cfo);
finance.Add(accountant);

// Build the whole company
var company = new Department("Acme Corp");
company.Add(ceo);
company.Add(engineering);
company.Add(finance);

// Ask the whole company — one call, rolls up everything
Console.WriteLine("=== Full Company ===");
company.GetDetails();

// Ask just one department — same call, same interface
Console.WriteLine("\n=== Engineering Only ===");
engineering.GetDetails();

// Ask a single employee — same call, same interface
Console.WriteLine("\n=== Single Employee ===");
dev1.GetDetails();

Output:

=== Full Company ===
[Acme Corp] Total: £487,000
  - Alice (CEO) (£120,000)
  [Engineering] Total: £222,000
    - Bob (CTO) (£95,000)
    - Carol (Developer) (£65,000)
    - David (Developer) (£62,000)
  [Finance] Total: £145,000
    - Eve (CFO) (£90,000)
    - Frank (Accountant) (£55,000)

=== Engineering Only ===
[Engineering] Total: £222,000
  - Bob (CTO) (£95,000)
  - Carol (Developer) (£65,000)
  - David (Developer) (£62,000)

=== Single Employee ===
- Carol (Developer) (£65,000)

company.GetDetails(), engineering.GetDetails(), and dev1.GetDetails(): the same call on three different levels of the tree. The caller never checked what it was talking to. That's the Composite pattern.

When to Use it

Use Composite when you need to represent part-whole hierarchies, like trees where individual items and groups of items need to be used interchangeably.

It also works well when you want client code to treat single objects and collections of objects uniformly, without any special-casing.

And it's a good fit when the structure can be nested to any depth and that depth shouldn't affect how the caller interacts with it.

4. The Decorator Design Pattern

Real World Example

Think of ordering a coffee at a cafe. You start with a plain espresso. Then you ask for milk. Then vanilla syrup. Then whipped cream on top. Each addition wraps around or adds to what was already there, adding its own cost and its own description. The espresso at the centre never changes. You're just layering on top of it, one addition at a time. You could add two shots of syrup. You could skip the milk entirely. Every combination is possible without creating a new type of coffee for each one.

That's the Decorator pattern. You start with a base object and wrap it in layers. Each layer adds its own behaviour and then delegates to whatever is underneath it.

Problems it solves:

  • What if you needed a class for every combination? EspressoWithMilk, EspressoWithMilkAndVanilla, EspressoWithMilkAndVanillaAndCream...the list explodes. Decorator adds behaviour at runtime, so you never need those classes.

  • What if the base coffee shouldn't change? It does not. The espresso class stays untouched. The decorators wrap around it and extend it independently.

  • What if a new topping needs to be added? You create one new decorator class. Every existing combination still works exactly as before.

In simple terms, you wrap an object in one or more layers, where each layer adds its own behaviour before or after delegating to the layer beneath it.

Wikipedia describes it like this:

"The decorator pattern is a design pattern that allows behaviour to be added to an individual object, dynamically, without affecting the behaviour of other instances of the same class." (Source)

Programming Example:

The coffee is the component. Each topping is a decorator. Every decorator wraps the component and adds to its description and cost.

// The component interface — every coffee, plain or decorated, shares this
public interface ICoffee
{
    string GetDescription();
    double GetCost();
}

// The base component — a plain espresso
public class Espresso : ICoffee
{
    public string GetDescription() => "Espresso";
    public double GetCost()        => 1.00;
}

// The base decorator — wraps any ICoffee and delegates to it
public abstract class CoffeeDecorator : ICoffee
{
    protected readonly ICoffee _coffee;

    protected CoffeeDecorator(ICoffee coffee) { _coffee = coffee; }

    public virtual string GetDescription() => _coffee.GetDescription();
    public virtual double GetCost()        => _coffee.GetCost();
}

// Concrete decorators — each one adds its own layer
public class Milk : CoffeeDecorator
{
    public Milk(ICoffee coffee) : base(coffee) { }

    public override string GetDescription() => _coffee.GetDescription() + ", Milk";
    public override double GetCost()        => _coffee.GetCost() + 0.30;
}

public class VanillaSyrup : CoffeeDecorator
{
    public VanillaSyrup(ICoffee coffee) : base(coffee) { }

    public override string GetDescription() => _coffee.GetDescription() + ", Vanilla Syrup";
    public override double GetCost()        => _coffee.GetCost() + 0.50;
}

public class WhippedCream : CoffeeDecorator
{
    public WhippedCream(ICoffee coffee) : base(coffee) { }

    public override string GetDescription() => _coffee.GetDescription() + ", Whipped Cream";
    public override double GetCost()        => _coffee.GetCost() + 0.75;
}

Now let's see it in action:

// A plain espresso
ICoffee order = new Espresso();
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

// Wrap it with milk
order = new Milk(order);
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

// Wrap it with vanilla syrup on top
order = new VanillaSyrup(order);
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

// Wrap it with whipped cream on top of that
order = new WhippedCream(order);
Console.WriteLine($"{order.GetDescription()} => £{order.GetCost():F2}");

Output:

Espresso => £1.00
Espresso, Milk => £1.30
Espresso, Milk, Vanilla Syrup => £1.80
Espresso, Milk, Vanilla Syrup, Whipped Cream => £2.55

Each line is a new layer wrapped around the previous one. The espresso never changed. The cost and description grew with every wrapper. That's the Decorator pattern.

When to Use it

Use the Decorator pattern when you want to add responsibilities to individual objects without affecting other objects of the same class.

It's also a good choice when subclassing would lead to an explosion of classes to cover every possible combination of behaviours.

And use it when you need to be able to stack behaviours in any order at runtime, independently of each other.

5. The Facade Design Pattern

Real World Example

Think of clicking "Place Order" on a shopping website. In that single click, several things happen behind the scenes: the system checks whether the item is in stock, your payment is charged, a shipping label is generated, and a confirmation email is sent to you. You don't see any of that. You click one button and get one result. The complexity of four separate systems is hidden behind a single, clean action.

That's the Facade pattern: one simple interface in front of many complex moving parts. The caller doesn't need to know what's happening behind the scenes.

Problems it solves:

  • What if the client had to call each subsystem directly? Check inventory, then process payment, then generate a label, and then send an email, all in the right order, handling each failure separately. The Facade wraps all of that into one call.

  • What if one of the subsystems changes? The Facade absorbs the change. The client code never needs to know. Only the Facade is updated.

  • What if different clients need the same flow? They all call the same Facade method. The logic is in one place, not duplicated across every caller.

In simple terms, you provide a single, simple interface that hides the complexity of a set of subsystems behind it.

Wikipedia describes it like this:

"The facade pattern (also spelled façade) is a software-design pattern commonly used in object-oriented programming. Analogous to a facade in architecture, a facade is an object that serves as a front-facing interface masking more complex underlying or structural code."(Source)

Programming Example:

Each subsystem does its own job. The OrderFacade is the single entry point that coordinates all of them. The client only ever talks to the facade.

// Subsystem 1: checks whether the item is available
public class InventoryService
{
    public bool CheckStock(string item)
    {
        Console.WriteLine($"Inventory: Checking stock for {item}.");
        return true;
    }
}

// Subsystem 2: handles the payment
public class PaymentService
{
    public bool ProcessPayment(string cardNumber, double amount)
    {
        Console.WriteLine($"Payment: Charging £{amount:F2} to card ending {cardNumber[^4..]}.");
        return true;
    }
}

// Subsystem 3: generates a shipping label
public class ShippingService
{
    public string GenerateLabel(string item, string address)
    {
        Console.WriteLine($"Shipping: Generating label for {item} to {address}.");
        return "TRACK-29384";
    }
}

// Subsystem 4: sends the confirmation email
public class EmailService
{
    public void SendConfirmation(string email, string trackingCode)
    {
        Console.WriteLine($"Email: Confirmation sent to {email}. Tracking code: {trackingCode}.");
    }
}

// The Facade — one method, hides all four subsystems
public class OrderFacade
{
    private readonly InventoryService _inventory = new();
    private readonly PaymentService   _payment   = new();
    private readonly ShippingService  _shipping  = new();
    private readonly EmailService     _email     = new();

    public void PlaceOrder(string item, string cardNumber, double amount, string address, string email)
    {
        Console.WriteLine("=== Placing Order ===");

        if (!_inventory.CheckStock(item))
        {
            Console.WriteLine("Order failed: item out of stock.");
            return;
        }

        if (!_payment.ProcessPayment(cardNumber, amount))
        {
            Console.WriteLine("Order failed: payment declined.");
            return;
        }

        string trackingCode = _shipping.GenerateLabel(item, address);
        _email.SendConfirmation(email, trackingCode);

        Console.WriteLine($"\nOrder complete. Your tracking code is {trackingCode}.");
    }
}

Now let's see it in action:

OrderFacade store = new OrderFacade();

store.PlaceOrder(
    item:       "Wireless Headphones",
    cardNumber: "4111111111111234",
    amount:     79.99,
    address:    "42 Maple Street, London",
    email:      "customer@email.com"
);

Output:

=== Placing Order ===
Inventory: Checking stock for Wireless Headphones.
Payment: Charging £79.99 to card ending 1234.
Shipping: Generating label for Wireless Headphones to 42 Maple Street, London.
Email: Confirmation sent to customer@email.com. Tracking code: TRACK-29384.

Order complete. Your tracking code is TRACK-29384.

The client called one method. Four subsystems ran in the right order. None of that complexity was visible to the caller. That is the Facade.

When to Use it

Use Facade when you want to provide a simple interface to a complex subsystem so callers aren't burdened by its internals.

It also works well when you want to layer your system so that high-level code talks to facades, not directly to low-level subsystems.

And it's a good choice when you want a single entry point that coordinates a sequence of steps across multiple services.

6. The Flyweight Design Pattern

Real World Example

Think of a game that renders a forest. The forest has ten thousand trees. Each tree has a type name, a colour, and a texture. But most of those trees are Oaks, and all Oaks look exactly the same.

Creating ten thousand separate objects, each storing the same name, colour, and texture, wastes enormous amounts of memory. Instead, you create one shared Oak object that holds all that data. Every Oak tree in the forest points to that same shared object and only stores its own position on the map.

That's the Flyweight pattern. The data that's the same across many instances is shared. The data that's unique per instance is stored separately and passed in only when needed.

Problems it solves:

  • What if you created a full object for every single tree? With ten thousand trees, you store the same name, colour, and texture ten thousand times. Flyweight stores that shared data once and reuses it everywhere.

  • What if a new tree type is introduced? The factory creates one new shared object for it. Every tree of that type immediately uses it without any extra memory.

  • What if the forest needs to render each tree at its own position? The position is unique per tree, so it's stored on the tree itself and passed to the shared object only at render time. The shared object never holds it.

In simple terms, you split an object's data into what's shared across many instances and what's unique per instance. Share the common part. Pass the unique part in only when needed.

Wikipedia describes it like this:

"A flyweight is an object that minimizes memory usage by sharing as much data as possible with other similar objects. It is a way to use objects in large numbers when a simple repeated representation would use an unacceptable amount of memory." (Source)

Programming ExampleL

TreeType is the flyweight: it holds shared data. Tree holds only the unique position and a reference to a shared TreeType. The factory ensures each TreeType is created only once.

// The flyweight — holds shared intrinsic state (same for all trees of this type)
public class TreeType
{
    public string Name    { get; }
    public string Colour  { get; }
    public string Texture { get; }

    public TreeType(string name, string colour, string texture)
    {
        Name    = name;
        Colour  = colour;
        Texture = texture;
    }

    public void Render(int x, int y)
    {
        Console.WriteLine($"Rendering {Name} tree ({Colour}, {Texture}) at ({x}, {y})");
    }
}

// The flyweight factory — creates and caches tree types so they are never duplicated
public class TreeTypeFactory
{
    private readonly Dictionary<string, TreeType> _cache = new();

    public TreeType GetTreeType(string name, string colour, string texture)
    {
        string key = $"{name}_{colour}_{texture}";

        if (!_cache.ContainsKey(key))
        {
            Console.WriteLine($"Factory: Creating new TreeType for '{name}'.");
            _cache[key] = new TreeType(name, colour, texture);
        }

        return _cache[key];
    }

    public int TotalTypes => _cache.Count;
}

// The context — holds unique extrinsic state (position) and a reference to a shared flyweight
public class Tree
{
    private readonly int      _x;
    private readonly int      _y;
    private readonly TreeType _type;

    public Tree(int x, int y, TreeType type)
    {
        _x    = x;
        _y    = y;
        _type = type;
    }

    public void Render() => _type.Render(_x, _y);
}

// The forest — plants trees using shared flyweights
public class Forest
{
    private readonly List<Tree>      _trees   = new();
    private readonly TreeTypeFactory _factory = new();

    public void PlantTree(int x, int y, string name, string colour, string texture)
    {
        TreeType type = _factory.GetTreeType(name, colour, texture);
        _trees.Add(new Tree(x, y, type));
    }

    public void Render()
    {
        foreach (var tree in _trees)
            tree.Render();
    }

    public int TreeCount     => _trees.Count;
    public int TreeTypeCount => _factory.TotalTypes;
}

Now let's see it in action:

Forest forest = new Forest();

// Plant 6 trees — but only 2 unique types
forest.PlantTree(1,  5,  "Oak",  "Dark Green",  "Rough bark");
forest.PlantTree(3,  12, "Oak",  "Dark Green",  "Rough bark");
forest.PlantTree(7,  2,  "Oak",  "Dark Green",  "Rough bark");
forest.PlantTree(10, 8,  "Pine", "Light Green", "Smooth bark");
forest.PlantTree(15, 3,  "Pine", "Light Green", "Smooth bark");
forest.PlantTree(20, 14, "Pine", "Light Green", "Smooth bark");

forest.Render();

Console.WriteLine($"\nTrees planted:              {forest.TreeCount}");
Console.WriteLine($"Unique tree types in memory: {forest.TreeTypeCount}");

Output:

Factory: Creating new TreeType for 'Oak'.
Factory: Creating new TreeType for 'Pine'.
Rendering Oak tree (Dark Green, Rough bark) at (1, 5)
Rendering Oak tree (Dark Green, Rough bark) at (3, 12)
Rendering Oak tree (Dark Green, Rough bark) at (7, 2)
Rendering Pine tree (Light Green, Smooth bark) at (10, 8)
Rendering Pine tree (Light Green, Smooth bark) at (15, 3)
Rendering Pine tree (Light Green, Smooth bark) at (20, 14)

Trees planted:              6
Unique tree types in memory: 2

Six trees, but only two TreeType objects were ever created. Scale that to ten thousand trees and the factory still creates exactly two. The positions are unique per tree, and the appearance is shared. That's the Flyweight.

When to Use it

Use Flyweight when your application needs to create a very large number of similar objects that would otherwise consume too much memory.

It's also useful when most of the object's state can be made shared across instances, with only a small part being unique per instance.

And it's a good choice when the unique part of the state can be passed in externally rather than stored inside every object.

7. The Proxy Design Pattern

Real World Example

Think of a security guard at the entrance of an office building. You can't walk straight into the building. You have to go through the guard first. The guard checks your name against the authorised list, logs your visit, and only then lets you through. If you're not on the list, you're turned away. The building itself never deals with any of that. It just lets people in. All the checking, logging, and decision-making happens at the guard (the proxy) before the building ever gets involved.

That's the Proxy pattern. It sits between the caller and the real object, controls what gets through, and can add behaviour like access checks or logging without the real object knowing anything about it.

Problems it solves:

  • What if anyone could walk straight into the building? There would be no access control. The proxy intercepts every request and decides whether it should be allowed through.

  • What if you need to log every entry without changing the building? The proxy handles it. The real building stays simple and focused on its own job.

  • What if the real object is expensive to create and you want to delay that? The proxy can hold off creating it until someone actually passes the check and needs it.

In simple terms, you place an object in front of another object to control access to it. The caller thinks it's talking directly to the real object, but the proxy is handling it first.

Wikipedia describes it like this:

"A proxy, in its most general form, is a class functioning as an interface to something else. The proxy could interface to anything: a network connection, a large object in memory, a file, or some other resource that is expensive or impossible to duplicate." (Source)

Programming Example:

The client talks to IBuilding. The SecurityGuard is the proxy: it implements the same interface, controls access, and only lets authorised visitors through to the OfficeBuilding.

// The subject interface — the building and the proxy both implement this
public interface IBuilding
{
    void Enter(string visitorName);
}

// The real subject — the actual building, just grants entry
public class OfficeBuilding : IBuilding
{
    public void Enter(string visitorName)
    {
        Console.WriteLine($"Building: {visitorName} has entered.");
    }
}

// The proxy — the security guard controls who gets through
public class SecurityGuard : IBuilding
{
    private readonly OfficeBuilding _building          = new();
    private readonly List<string>   _authorisedVisitors = new() { "Alice", "Bob", "Carol" };

    public void Enter(string visitorName)
    {
        Console.WriteLine($"Guard: {visitorName} is requesting entry.");

        if (_authorisedVisitors.Contains(visitorName))
        {
            Console.WriteLine("Guard: ID verified. Access granted.");
            _building.Enter(visitorName);
        }
        else
        {
            Console.WriteLine($"Guard: {visitorName} is not on the list. Access denied.");
        }
    }
}

Now let's see it in action:

IBuilding entrance = new SecurityGuard();

entrance.Enter("Alice");
Console.WriteLine();
entrance.Enter("David");
Console.WriteLine();
entrance.Enter("Bob");

Output:

Guard: Alice is requesting entry.
Guard: ID verified. Access granted.
Building: Alice has entered.

Guard: David is requesting entry.
Guard: David is not on the list. Access denied.

Guard: Bob is requesting entry.
Guard: ID verified. Access granted.
Building: Bob has entered.

The client called Enter() on what it thought was the building. It was actually the security guard. The guard decided what happened. The building only ever saw the people who were allowed through. That's the Proxy.

When to Use it

Use Proxy when you need access control, like only letting certain callers through to the real object.

It's a good fit when you want to add behaviour such as logging, caching, or validation without changing the real object.

And you can use it when the real object is expensive to create and you want to delay or guard that creation until it's truly needed.

Behavioral Design Patterns

Simply put, behavioral patterns are all about how objects communicate and share responsibility. They focus on the assignment of responsibilities between objects, and how objects cooperate to get a job done.

Wikipedia describes them as:

"In software engineering, behavioral design patterns are design patterns that identify common communication patterns among objects. By doing so, these patterns increase flexibility in carrying out this communication." (Source)

Behavioral design patterns describe how objects interact and distribute responsibility, not just how they're structured. They focus on communication between objects: who talks to whom, and how much each side knows about the other.

There are 11 behavioral design patterns:

  1. Chain of Responsibility: Passes a request along a chain of handlers, letting each one decide to handle it or pass it on.

  2. Command: Encapsulates a request as an object, letting you parameterize clients, queue actions, and support undo.

  3. Interpreter: Given a language, defines a representation for its grammar along with an interpreter that evaluates sentences in it.

  4. Iterator: Provides a way to access the elements of a collection sequentially without exposing how it's built underneath.

  5. Mediator: Defines an object that encapsulates how a set of objects interact, so they don't refer to each other directly.

  6. Memento: Captures an object's internal state so it can be restored later, without breaking encapsulation.

  7. Observer: Defines a one-to-many dependency so that when one object changes state, everything depending on it is notified automatically.

  8. State: Lets an object change its behaviour when its internal state changes, as if it had changed its class.

  9. Strategy: Defines a family of interchangeable algorithms and lets the client pick which one to use at runtime.

  10. Template Method: Defines the skeleton of an algorithm in a method, leaving some steps for subclasses to fill in.

  11. Visitor: Lets you define a new operation without changing the classes of the elements it operates on.

1. The Chain of Responsibility Design Pattern

Real World Example

Think of an expense approval process at a company. An employee submits a request to their director. If the amount is small enough, the director approves it and that's the end of it. If it's too large for the director to sign off on, it goes up to the vice president. If it's still too large, it goes up to the chief executive.

Each person in the chain only needs to know two things: what they're allowed to approve, and who to hand it to if they can't. The employee never needs to know who ends up approving it.

That's the Chain of Responsibility design pattern. A request travels along a chain of handlers until one of them deals with it, and each handler only cares about its own link in that chain.

Problems it solves:

  • What if the sender had to know exactly who should handle the request? That would tie the sender to a specific handler and break the moment the approval structure changed. The chain lets the sender submit the request without knowing who will end up handling it.

  • What if one handler could only ever approve or reject, with no fallback? Requests that fell outside its authority would simply fail. The chain lets a handler pass what it can't deal with further along.

  • What if you needed to change the approval structure? Rewiring which handler comes after which is enough. Neither the sender nor the other handlers need to change.

In simple terms, you pass a request along a chain of handlers. Each handler decides whether to deal with it or hand it off to the next one in line.

Wikipedia describes it like this:

"In object-oriented design, the chain-of-responsibility pattern is a behavioral design pattern consisting of a source of command objects and a series of processing objects. Each processing object contains logic that defines the types of command objects that it can handle; the rest are passed to the next processing object in the chain."

(Source)

Programming Example:

Each Approver knows its own approval limit and holds a reference to the next approver in the chain. The ExpenseRequest is passed along until someone can approve it, or nobody can.

// The request that travels along the chain
public class ExpenseRequest
{
    public string Description { get; }
    public decimal Amount     { get; }

    public ExpenseRequest(string description, decimal amount)
    {
        Description = description;
        Amount      = amount;
    }
}

// The handler, every link in the chain implements this
public abstract class Approver
{
    private Approver? _next;

    public void SetNext(Approver next) => _next = next;

    public void Approve(ExpenseRequest request)
    {
        if (CanApprove(request))
        {
            Console.WriteLine($"{GetType().Name}: Approved '{request.Description}' (${request.Amount}).");
        }
        else if (_next is not null)
        {
            Console.WriteLine($"{GetType().Name}: Can't approve '{request.Description}' (${request.Amount}). Passing it up.");
            _next.Approve(request);
        }
        else
        {
            Console.WriteLine($"{GetType().Name}: No one left to approve '{request.Description}' (${request.Amount}). Request denied.");
        }
    }

    protected abstract bool CanApprove(ExpenseRequest request);
}

// Concrete handlers, each with its own approval limit
public class Director : Approver
{
    protected override bool CanApprove(ExpenseRequest request) => request.Amount <= 1000;
}

public class VicePresident : Approver
{
    protected override bool CanApprove(ExpenseRequest request) => request.Amount <= 20000;
}

public class Chief : Approver
{
    protected override bool CanApprove(ExpenseRequest request) => request.Amount <= 50000;
}

Now let's see it in action:

Approver directorApprover = new Director();
Approver vpApprover       = new VicePresident();
Approver ceoApprover      = new Chief();

directorApprover.SetNext(vpApprover);
vpApprover.SetNext(ceoApprover);

directorApprover.Approve(new ExpenseRequest("Laptop", 800));
Console.WriteLine();
directorApprover.Approve(new ExpenseRequest("Team offsite", 12000));
Console.WriteLine();
directorApprover.Approve(new ExpenseRequest("New office lease", 90000));

Output:

Director: Approved 'Laptop' ($800).

Director: Can't approve 'Team offsite' ($12000). Passing it up.
VicePresident: Approved 'Team offsite' ($12000).

Director: Can't approve 'New office lease' ($90000). Passing it up.
VicePresident: Can't approve 'New office lease' ($90000). Passing it up.
Chief: No one left to approve 'New office lease' ($90000). Request denied.

The employee only ever talked to the director. Whether the director, the vice president, or the chief ended up approving it, was decided by the chain itself, not the employee.

When to Use it

Use Chain of Responsibility when more than one object might handle a request, and the handler isn't known in advance.

It's also a good choice when you want to issue a request without specifying the receiver explicitly.

And it's helpful when the set of handlers, and their order, should be configurable rather than hard-coded.

2. The Command Design Pattern

Real World Example

Think of a universal remote control. Every button is programmed to do one specific thing: turn a light on, turn a light off, and so on. When you press a button, the remote doesn't know or care how the light actually works internally. It just triggers the action that button was set up to perform. And because each button's action is a self-contained thing, the remote can also press it in reverse, undoing what it just did.

That's the Command pattern. A request "turn the light on" is wrapped up as its own object. The thing that triggers it doesn't need to know anything about how it's carried out.

Problems it solves:

  • What if the button had to know exactly how the light worked? Every button would need to be rewritten if the light's internals changed. Wrapping the action as a command means the remote never touches those details.

  • What if you wanted to undo the last action? Without a command object there's nothing to reverse, only a completed side effect. Wrapping the action gives you something you can also unwind.

  • What if you wanted to queue actions, log them, or trigger them later? A plain method call happens immediately and leaves nothing behind. A command is an object, so it can be stored, queued, and replayed.

In simple terms, you wrap a request up as an object, so the thing that triggers it doesn't need to know how it's carried out, and the action itself can be queued, logged, or undone.

Wikipedia describes it like this:

"The command pattern is a behavioral design pattern in which an object is used to encapsulate all information needed to perform an action or trigger an event at a later time." (Source)

Programming Example:

The RemoteControl is the invoker it only knows about ICommand. LightOnCommand and LightOffCommand are the concrete commands, each wrapping the Light receiver and the action to perform on it.

// The command interface, every action implements this
public interface ICommand
{
    void Execute();
    void Undo();
}

// The receiver, the object that actually does the work
public class Light
{
    private readonly string _room;

    public Light(string room) => _room = room;

    public void On()  => Console.WriteLine($"{_room} light: turned on.");
    public void Off() => Console.WriteLine($"{_room} light: turned off.");
}

// Concrete commands, each wraps a receiver and an action
public class LightOnCommand : ICommand
{
    private readonly Light _light;

    public LightOnCommand(Light light) => _light = light;

    public void Execute() => _light.On();
    public void Undo()    => _light.Off();
}

public class LightOffCommand : ICommand
{
    private readonly Light _light;

    public LightOffCommand(Light light) => _light = light;

    public void Execute() => _light.Off();
    public void Undo()    => _light.On();
}

// The invoker, it holds a command and triggers it without knowing what it does
public class RemoteControl
{
    private ICommand? _command;

    public void SetCommand(ICommand command) => _command = command;

    public void PressButton() => _command?.Execute();
    public void PressUndo()   => _command?.Undo();
}

Now let's see it in action:

var livingRoomLight = new Light("Living Room");
var remote          = new RemoteControl();

remote.SetCommand(new LightOnCommand(livingRoomLight));
remote.PressButton();

remote.SetCommand(new LightOffCommand(livingRoomLight));
remote.PressButton();

Console.WriteLine();
Console.WriteLine("Undoing last action...");
remote.PressUndo();

Output:

Living Room light: turned on.
Living Room light: turned off.

Undoing last action...
Living Room light: turned on.

The remote never called _light.On() or _light.Off() directly. It called Execute() and Undo() on whatever command it was holding. That's the Command pattern: the request itself became an object.

When to Use it

Use the Command pattern when you want to parameterize objects with an action to perform, rather than hard-coding it.

Reach for it when you need to queue, log, or support undo for requests.

And consider it when you want to decouple the object that invokes an action from the object that knows how to perform it.

3. The Interpreter Design Pattern

Real World Example

Think of a basic calculator reading an expression like (5 + 3) - 2. Nobody hardcodes a single method that handles every possible expression. Instead, the expression is broken down into small pieces: numbers and operation buttons, each of which knows how to evaluate itself and combine with the others. (5 + 3) - 2 becomes a subtraction of two things: the number 2, and the result of adding 5 and 3. Each piece only needs to know how to interpret itself.

That's the Interpreter pattern. A grammar is represented as a tree of small objects, and each one knows how to evaluate its own little piece of it.

Problems it solves:

  • What if you tried to evaluate an entire expression in one big method? It would grow unmanageable the moment the grammar got more complex. Breaking the grammar into small classes, one per rule, keeps each piece simple.

  • What if the grammar needed to grow? Adding a new operation, like multiplication, is just a new class. The existing pieces don't need to change.

  • What if the same expression needed to be evaluated more than once, or in different contexts? Because each piece is just an object, the same tree can be interpreted again without rebuilding it.

In simple terms, you represent a grammar as a tree of small objects, where each object knows how to interpret its own piece of the expression.

Wikipedia describes it like this:

"In computer programming, the interpreter pattern is a design pattern that specifies how to evaluate sentences in a language. The basic idea is to have a class for each symbol (terminal or nonterminal) in a specialized computer language." (Source)

Programming Example:

Number is the terminal expression, a plain value. Add and Subtract are non-terminal expressions, each combining two other expressions. Every node, terminal or not, knows how to Interpret() itself.

// The abstract expression, every node in the grammar implements this
public abstract class Expression
{
    public abstract int Interpret();
}

// A terminal expression, a plain number that needs no further interpretation
public class Number : Expression
{
    private readonly int _value;

    public Number(int value) => _value = value;

    public override int Interpret() => _value;
}

// Non-terminal expressions, each combines other expressions
public class Add : Expression
{
    private readonly Expression _left;
    private readonly Expression _right;

    public Add(Expression left, Expression right)
    {
        _left  = left;
        _right = right;
    }

    public override int Interpret() => _left.Interpret() + _right.Interpret();
}

public class Subtract : Expression
{
    private readonly Expression _left;
    private readonly Expression _right;

    public Subtract(Expression left, Expression right)
    {
        _left  = left;
        _right = right;
    }

    public override int Interpret() => _left.Interpret() - _right.Interpret();
}

Now let's see it in action:

// (5 plus 3) minus 2
Expression expression = new Subtract(
    new Add(new Number(5), new Number(3)),
    new Number(2)
);

Console.WriteLine($"Result: {expression.Interpret()}");

// (10 minus 4) plus (2 plus 2)
Expression another = new Add(
    new Subtract(new Number(10), new Number(4)),
    new Add(new Number(2), new Number(2))
);

Console.WriteLine($"Result: {another.Interpret()}");

Output:

Result: 6
Result: 10

Nothing ever evaluated the whole expression at once. Subtract asked its own _left and _right to interpret themselves, and those asked their own children, all the way down to plain numbers. That's the Interpreter pattern: the grammar interprets itself, one small piece at a time.

When to Use it

Use Interpreter when you have a simple language or grammar to evaluate, and representing it as a tree of expressions keeps it manageable.

It also works well when the grammar is relatively stable. For example, adding new rules means adding new classes, not rewriting existing ones.

And it's useful when you would rather have many small, focused classes than one large method trying to parse and evaluate everything at once.

4. The Iterator Design Pattern

Real World Example

Think of a bookshelf. You want to go through it one book at a time, from left to right, without needing to know whether the books are held in an array, multiple piles and stacks, or something else entirely. All you need is a way to ask "what's next?" and to know when you've reached the end. How the shelf actually stores its books internally is none of your concern.

That's the Iterator pattern. It gives you a consistent way to step through a collection, one element at a time, without exposing how that collection is built underneath.

Problems it solves:

  • What if the client had to know how the collection was stored internally to loop over it? Any change to that internal structure would break every piece of code that loops over it. The iterator hides that structure behind a simple "get next" interface.

  • What if you needed more than one traversal in progress at the same time? A single shared position wouldn't work. Each iterator keeps its own position, so multiple traversals can happen independently.

  • What if you wanted to loop over the collection using the language's own foreach? Implementing the iterator interface the language expects means your custom collection gets that support for free.

In simple terms, you give a collection a way to be walked through, one element at a time, without exposing how it's actually built underneath.

Wikipedia describes it like this:

"In object-oriented programming, the iterator pattern is a design pattern in which an iterator is used to traverse a container and access the container's elements." (Source)

Programming Example:

Bookshelf is the aggregate it exposes an IEnumerator<string> without revealing that it stores books in a List<string> internally. BookshelfIterator is the iterator that walks through them one at a time.

// The aggregate, exposes an iterator without revealing how books are stored
public class Bookshelf : IEnumerable<string>
{
    private readonly List<string> _books = new();

    public void Add(string title) => _books.Add(title);

    public IEnumerator<string> GetEnumerator() => new BookshelfIterator(_books);

    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
}

// The iterator, walks the collection one book at a time
public class BookshelfIterator : IEnumerator<string>
{
    private readonly List<string> _books;
    private int _position = -1;

    public BookshelfIterator(List<string> books) => _books = books;

    public string Current => _books[_position];

    object IEnumerator.Current => Current;

    public bool MoveNext()
    {
        _position++;
        return _position < _books.Count;
    }

    public void Reset() => _position = -1;

    public void Dispose() { }
}

Now let's see it in action:

var bookshelf = new Bookshelf();
bookshelf.Add("Clean Code");
bookshelf.Add("The Pragmatic Programmer");
bookshelf.Add("Design Patterns");

foreach (var book in bookshelf)
{
    Console.WriteLine($"On the shelf: {book}");
}

Output:

On the shelf: Clean Code
On the shelf: The Pragmatic Programmer
On the shelf: Design Patterns

The foreach loop never touched the List<string> inside Bookshelf directly. It called MoveNext() and Current on the BookshelfIterator, one step at a time. That's the Iterator pattern: the traversal logic lives outside the collection itself.

When to Use it

Use Iterator when you want to traverse a collection without exposing its internal structure.

It's also a good choice when you need to support multiple simultaneous traversals over the same collection.

And try it when you want your custom collection to work with the language's built-in iteration syntax, like foreach.

5. The Mediator Design Pattern

Real World Example

Think of an air traffic control tower. Planes don't radio each other directly to negotiate who lands first. That would be chaos: dozens of pilots all trying to coordinate with each other at once.

Instead, every plane talks only to the tower. The tower knows the state of the runway and tells each plane what to do. The planes never need to know how many other planes are around, or what they're doing.

That's the Mediator pattern. Instead of objects talking to each other directly, they all talk to one central object that coordinates them.

Problems it solves:

  • What if every aircraft had to communicate directly with every other aircraft? The number of connections would explode as more aircraft joined, and each one would need to know about all the others. The mediator means each aircraft only needs to know about the tower.

  • What if the coordination logic was scattered across every object involved? Changing how landings get prioritised would mean touching every aircraft. With a mediator, that logic lives in one place.

  • What if you wanted to add a new aircraft to the system? It only needs to know how to talk to the tower. It doesn't need to be introduced to every other aircraft already in the sky.

In simple terms, instead of letting objects talk to each other directly, you route all communication through one central object that knows how to coordinate them.

Wikipedia describes it like this:

"In software engineering, the mediator pattern defines an object that encapsulates how a set of objects interact. This pattern is considered to be a behavioral pattern due to the way it can alter the program's running behavior." (Source)

Programming Example:

ControlTower is the mediator. It's the only thing an Aircraft ever talks to. It decides whether a plane can land based on the state it holds, and no aircraft ever contacts another aircraft directly.

// The mediator interface
public interface IControlTower
{
    void RequestLanding(Aircraft requester);
}

// The concrete mediator, coordinates all the aircraft instead of letting them talk to each other
public class ControlTower : IControlTower
{
    private readonly List<Aircraft> _aircraft = new();
    private bool _runwayFree = true;

    public void Register(Aircraft aircraft) => _aircraft.Add(aircraft);

    public void RequestLanding(Aircraft requester)
    {
        if (_runwayFree)
        {
            _runwayFree = false;
            Console.WriteLine($"Tower: Runway clear. {requester.Name}, you are cleared to land.");
        }
        else
        {
            Console.WriteLine($"Tower: Runway occupied. {requester.Name}, please hold your position.");
        }
    }
}

// The colleague, only ever talks to the mediator, never to other aircraft directly
public class Aircraft
{
    public string Name { get; }

    private readonly IControlTower _tower;

    public Aircraft(string name, IControlTower tower)
    {
        Name   = name;
        _tower = tower;
    }

    public void RequestLanding()
    {
        Console.WriteLine($"{Name}: Requesting permission to land.");
        _tower.RequestLanding(this);
    }
}

Now let's see it in action:

var tower = new ControlTower();

var flight101 = new Aircraft("Flight 101", tower);
var flight202 = new Aircraft("Flight 202", tower);

tower.Register(flight101);
tower.Register(flight202);

flight101.RequestLanding();
flight202.RequestLanding();

Output:

Flight 101: Requesting permission to land.
Tower: Runway clear. Flight 101, you are cleared to land.
Flight 202: Requesting permission to land.
Tower: Runway occupied. Flight 202, please hold your position.

Flight 101 and Flight 202 never spoke to each other. Neither one even knows the other exists. Both only ever talked to the tower, and the tower decided what happened next. That's the Mediator pattern.

When to Use it

Use Mediator when a group of objects communicate in complex, tangled ways, and you want to centralise that communication.

It's also helpful when you want to reuse objects independently, without them being locked together by direct references to each other.

And reach for it when the way objects interact changes often, and you'd rather change it in one place than in every object involved.

6. The Memento Design Pattern

Real World Example

Think of the undo history in a text editor. Every so often, the editor quietly takes a snapshot of what the document looks like. It doesn't ask the document to expose its internals to do this. It just captures a copy of the content at that moment.

When you press undo, the editor hands that snapshot back, and the document restores itself to exactly how it was. The history keeps a pile of these snapshots, but it never looks inside them or changes them. It only stores them and hands them back.

That's the Memento pattern. It lets you capture and restore an object's state without exposing how that state is structured internally.

Problems it solves:

  • What if undo required exposing every private field of the document? That would break encapsulation, and any change to the document's internals would ripple out to whatever handles undo. The memento hides that structure inside an object only the document itself knows how to read.

  • What if the history needed to inspect or modify old snapshots? It shouldn't be able to. The caretaker only stores and returns mementos, it never reads or changes what's inside them.

  • What if you needed several restore points, not just one? Because each memento is just an object, they can be stacked, listed, or discarded, giving you as many restore points as you want to keep.

In simple terms, you capture an object's state in a snapshot you can restore later, without exposing how that state is put together internally.

Wikipedia describes it like this:

"The memento pattern is a software design pattern that provides the ability to restore an object to its previous state (undo via rollback)."

(Source)

Programming Example:

TextEditor is the originator: it creates EditorMemento snapshots of itself and can restore from one. History is the caretaker: it stores mementos on a stack without ever looking inside them.

// The memento, an immutable snapshot of the editor's state
public class EditorMemento
{
    public string Content { get; }

    public EditorMemento(string content) => Content = content;
}

// The originator, creates and restores from mementos of its own state
public class TextEditor
{
    public string Content { get; private set; } = string.Empty;

    public void Write(string text) => Content += text;

    public EditorMemento Save() => new(Content);

    public void Restore(EditorMemento memento) => Content = memento.Content;
}

// The caretaker, stores mementos without ever looking inside them
public class History
{
    private readonly Stack<EditorMemento> _snapshots = new();

    public void Save(EditorMemento memento) => _snapshots.Push(memento);

    public EditorMemento Undo() => _snapshots.Pop();
}

Now let's see it in action:

var editor  = new TextEditor();
var history = new History();

editor.Write("Hello");
history.Save(editor.Save());

editor.Write(", world");
history.Save(editor.Save());

editor.Write("!!!");
Console.WriteLine($"Current: {editor.Content}");

editor.Restore(history.Undo());
Console.WriteLine($"After undo: {editor.Content}");

editor.Restore(history.Undo());
Console.WriteLine($"After undo: {editor.Content}");

Output:

Current: Hello, world!!!
After undo: Hello, world
After undo: Hello

History never read or changed the text inside a snapshot. It just pushed mementos on and popped them off. Only TextEditor knew what to do with the content inside one. That's the Memento pattern.

When to Use it

Use Memento when you need undo/redo functionality and want to capture state without exposing an object's internals.

It's also a good choice when taking a snapshot directly would break encapsulation by exposing private fields.

And it's helpful when you want the object that stores history to stay dumb: like holding snapshots without knowing or caring what's inside them.

7. The Observer Design Pattern

Real World Example

Think of subscribing to a YouTube channel. You don't sit there refreshing the page, checking if a new video has been uploaded. You subscribe once, and the moment the channel uploads something, you get notified automatically.

The channel doesn't know or care what each subscriber does with that notification. It just knows it has a list of subscribers, and when something changes, it tells all of them.

That's the Observer pattern. One object holds a list of dependents, and whenever its state changes, it notifies every one of them automatically.

Problems it solves:

  • What if every subscriber had to keep checking the channel for updates? That would waste effort and add delay. The channel notifying its subscribers directly means they find out the moment it happens.

  • What if the channel had to know exactly what each subscriber wanted to do with a new video? It shouldn't need to. The channel only calls Notify(), each subscriber decides for itself what that means.

  • What if you wanted to add or remove subscribers at runtime? The channel doesn't need to change. It just keeps a list, and subscribing or unsubscribing only ever affects that list.

In simple terms, one object keeps a list of dependents and automatically notifies all of them whenever its own state changes.

Wikipedia describes it like this:

"The observer pattern is a software design pattern in which an object, named the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes, usually by calling one of their methods." (Source)

Programming Example:

YouTubeChannel is the subject: it keeps a list of ISubscribers and notifies all of them whenever a video is uploaded. Subscriber is the concrete observer, deciding for itself what to do with that notification.

// The observer interface, every subscriber implements this
public interface ISubscriber
{
    void Notify(string channelName, string videoTitle);
}

// The concrete observer
public class Subscriber : ISubscriber
{
    private readonly string _name;

    public Subscriber(string name) => _name = name;

    public void Notify(string channelName, string videoTitle)
    {
        Console.WriteLine($"{_name}: {channelName} just uploaded '{videoTitle}'!");
    }
}

// The subject, keeps track of its subscribers and notifies them of changes
public class YouTubeChannel
{
    private readonly string _name;
    private readonly List<ISubscriber> _subscribers = new();

    public YouTubeChannel(string name) => _name = name;

    public void Subscribe(ISubscriber subscriber)   => _subscribers.Add(subscriber);
    public void Unsubscribe(ISubscriber subscriber) => _subscribers.Remove(subscriber);

    public void UploadVideo(string title)
    {
        Console.WriteLine($"{_name}: Uploaded '{title}'.");

        foreach (var subscriber in _subscribers)
        {
            subscriber.Notify(_name, title);
        }
    }
}

Now let's see it in action:

var channel = new YouTubeChannel("Code With Isaiah");

var alice = new Subscriber("Alice");
var bob   = new Subscriber("Bob");

channel.Subscribe(alice);
channel.Subscribe(bob);

channel.UploadVideo("Design Patterns Explained");

channel.Unsubscribe(bob);
channel.UploadVideo("Understanding the Observer Pattern");

Output:

Code With Isaiah: Uploaded 'Design Patterns Explained'.
Alice: Code With Isaiah just uploaded 'Design Patterns Explained'!
Bob: Code With Isaiah just uploaded 'Design Patterns Explained'!
Code With Isaiah: Uploaded 'Understanding the Observer Pattern'.
Alice: Code With Isaiah just uploaded 'Understanding the Observer Pattern'!

Once Bob unsubscribed, he stopped hearing about new uploads entirely. The channel never singled him out, it just no longer had him on the list it notifies. That's the Observer pattern.

When to Use it

Use Observer when a change to one object should automatically update an unknown number of others.

It's also useful when you want objects to stay loosely coupled: the subject only knows about an observer interface, never concrete details.

And it's a good option when the number of dependents can grow or shrink at runtime, such as subscribing and unsubscribing.

8. The State Design Pattern

Real World Example

Think of an online order moving through its lifecycle: pending, then shipped, then delivered. What "moving to the next step" actually means is different at every stage. From pending it means handing the package to a courier. From shipped it means marking it as received. From delivered, there's nowhere left to go. Rather than one giant method full of if checks for every possible stage, each stage can just know what comes after it.

That's the State pattern. The object's behaviour changes based on its current state, and each state knows how to transition to the next one.

Problems it solves:

  • What if one method had to handle every stage with a long chain of conditionals? It would grow harder to follow every time a new stage was added. Giving each stage its own class keeps the logic for that stage self-contained.

  • What if adding a new stage meant editing that same giant method? It's easy to introduce a bug in an unrelated stage while doing so. A new state is just a new class, dropped in alongside the others.

  • What if the object needed to behave completely differently depending on where it was in its lifecycle? Delegating to the current state object means the context doesn't need to know the details. It just asks the current state what to do.

In simple terms, you let an object change its behaviour by changing which state object it's currently holding, so the object appears to change how it acts as its state changes.

Wikipedia describes it like this:

"The state pattern is a behavioral software design pattern that allows an object to alter its behavior when its internal state changes. This pattern is close to the concept of finite-state machines." (Source)

Programming Example:

Order is the context: it holds whatever IOrderState it's currently in and delegates to it. Each concrete state, PendingState, ShippedState, DeliveredState, knows what the next state should be.

// The state interface, every state implements this
public interface IOrderState
{
    void Next(Order order);
    string Name { get; }
}

// The context, delegates behaviour to whatever state it currently holds
public class Order
{
    public IOrderState State { get; set; } = new PendingState();

    public void Next()
    {
        Console.WriteLine($"Order is currently: {State.Name}");
        State.Next(this);
    }
}

// Concrete states, each knows what comes after it
public class PendingState : IOrderState
{
    public string Name => "Pending";

    public void Next(Order order) => order.State = new ShippedState();
}

public class ShippedState : IOrderState
{
    public string Name => "Shipped";

    public void Next(Order order) => order.State = new DeliveredState();
}

public class DeliveredState : IOrderState
{
    public string Name => "Delivered";

    public void Next(Order order)
    {
        Console.WriteLine("Order has already been delivered. Nothing left to do.");
    }
}

Now let's see it in action:

var order = new Order();

order.Next();
order.Next();
order.Next();
order.Next();

Output:

Order is currently: Pending
Order is currently: Shipped
Order is currently: Delivered
Order has already been delivered. Nothing left to do.

Order never checked "if pending, do this, if shipped, do that." It just asked its current state what to do next, and the state itself decided what came after. That's the State pattern.

When to Use it

Use State when an object's behaviour depends on its state, and it must change that behaviour at runtime as the state changes.

It's also helpful when you have large conditional blocks that branch on the object's current state or type.

And choose it when transitions between states should be explicit and self-contained, rather than scattered across one big method.

9. The Strategy Design Pattern

Real World Example

Think of checking out of an online store. You can pay by credit card, or you can pay through PayPal. The shopping cart doesn't care which one you pick. It just knows the total, hands it to whichever payment method you chose, and lets that method handle the details of actually charging you. Swap the payment method, and the cart's own code never changes.

That's the Strategy pattern. An algorithm (in this case "how to pay") is pulled out into its own interchangeable object, and the client just picks which one to use.

Problems it solves:

  • What if the cart had a big if/else for every payment method? Adding a new one would mean editing that method every time. Pulling each payment method out into its own class means the cart never needs to change.

  • What if you wanted to swap the algorithm at runtime? A hardcoded method can't be swapped. A strategy object can simply be replaced with another one that implements the same interface.

  • What if two different payment methods needed to share a common interface but nothing else? Each one implements the strategy interface, but its internal details (a card number here, an email there) stay private to it.

In simple terms, you pull an algorithm out into its own interchangeable object, so the class using it doesn't need to know or care which specific version is running.

Wikipedia describes it like this:

"The strategy pattern is a behavioral software design pattern that enables selecting an algorithm at runtime." (Source)

Programming Example:

ShoppingCart is the context: it holds an IPaymentStrategy and delegates the actual payment to it. CreditCardPayment and PayPalPayment are concrete strategies, each a different way to pay.

// The strategy interface, every payment method implements this
public interface IPaymentStrategy
{
    void Pay(decimal amount);
}

// Concrete strategies, each a different way to pay
public class CreditCardPayment : IPaymentStrategy
{
    private readonly string _cardNumber;

    public CreditCardPayment(string cardNumber) => _cardNumber = cardNumber;

    public void Pay(decimal amount)
    {
        Console.WriteLine($"Charged ${amount} to credit card ending in {_cardNumber[^4..]}.");
    }
}

public class PayPalPayment : IPaymentStrategy
{
    private readonly string _email;

    public PayPalPayment(string email) => _email = email;

    public void Pay(decimal amount)
    {
        Console.WriteLine($"Charged ${amount} via PayPal account {_email}.");
    }
}

// The context, holds a strategy and delegates the actual payment work to it
public class ShoppingCart
{
    private readonly decimal _total;
    private IPaymentStrategy? _paymentMethod;

    public ShoppingCart(decimal total) => _total = total;

    public void SetPaymentMethod(IPaymentStrategy method) => _paymentMethod = method;

    public void Checkout()
    {
        if (_paymentMethod is null)
        {
            Console.WriteLine("No payment method selected.");
            return;
        }

        _paymentMethod.Pay(_total);
    }
}

Now let's see it in action:

var cart = new ShoppingCart(59.99m);

cart.SetPaymentMethod(new CreditCardPayment("4111 1111 1111 1111"));
cart.Checkout();

cart.SetPaymentMethod(new PayPalPayment("isaiah@example.com"));
cart.Checkout();

Output:

Charged $59.99 to credit card ending in 1111.
Charged $59.99 via PayPal account isaiah@example.com.

ShoppingCart never knew how a payment actually got processed. It just called Pay() on whatever strategy it was holding at the time. That's the Strategy pattern: the algorithm is swapped out, the class using it stays exactly the same.

When to Use it

Use Strategy when you have several variants of an algorithm, and want to switch between them at runtime.

It's also helpful when you want to avoid a class full of conditionals that pick behaviour based on a type or flag.

And it's a solid choice when related classes only differ in the behaviour they use, and that behaviour should be interchangeable.

10. The Template Method Design Pattern

Real World Example

Think of making a hot drink, tea or coffee. Both follow the exact same basic steps: boil water, brew, pour into a cup, and add something to taste. What differs is only two of those steps: tea gets steeped, and coffee gets brewed through grounds. Tea gets lemon, and coffee gets sugar and milk. The overall recipe never changes, only the specific details of a couple of steps within it.

That's the Template Method pattern. A base class defines the fixed skeleton of an algorithm, and subclasses only fill in the steps that are actually allowed to vary.

Problems it solves:

  • What if every beverage repeated the entire recipe from scratch? Boiling water and pouring into a cup would be duplicated in every single class. The template method keeps those steps in one place, written once.

  • What if a subclass could reorder the steps, or skip one entirely? That would let each beverage break the overall recipe. Because the algorithm's skeleton lives in the base class as a single method, the order and structure stay fixed.

  • What if you wanted to add a new beverage? Only the steps that differ, brewing and condiments, need to be written. Everything else is already handled by the base class.

In simple terms, you define the fixed skeleton of an algorithm in a base class, and let subclasses fill in only the steps that are actually allowed to differ.

Wikipedia describes it like this:

"In object-oriented programming, the template method is one of the behavioral design patterns identified by Gamma et al. in the book Design Patterns. The template method is a method in a superclass, usually an abstract superclass, and defines the skeleton of an operation in terms of a number of high-level steps." (Source)

Programming Example:

Beverage defines Prepare() as the template method: the fixed sequence of steps. Tea and Coffee only override Brew() and AddCondiments(), the two steps that are actually allowed to vary.

// The abstract class, defines the skeleton of the algorithm
public abstract class Beverage
{
    // The template method, the steps and their order never change
    public void Prepare()
    {
        BoilWater();
        Brew();
        PourInCup();
        AddCondiments();
    }

    private void BoilWater() => Console.WriteLine("Boiling water.");
    private void PourInCup() => Console.WriteLine("Pouring into cup.");

    // Steps left for subclasses to fill in
    protected abstract void Brew();
    protected abstract void AddCondiments();
}

// A concrete class, fills in the steps specific to tea
public class Tea : Beverage
{
    protected override void Brew() => Console.WriteLine("Steeping the tea bag.");
    protected override void AddCondiments() => Console.WriteLine("Adding lemon.");
}

// Another concrete class, fills in the steps specific to coffee
public class Coffee : Beverage
{
    protected override void Brew() => Console.WriteLine("Brewing the coffee grounds.");
    protected override void AddCondiments() => Console.WriteLine("Adding sugar and milk.");
}

Now let's see it in action:

Beverage tea    = new Tea();
Beverage coffee = new Coffee();

tea.Prepare();
Console.WriteLine();
coffee.Prepare();

Output:

Boiling water.
Steeping the tea bag.
Pouring into cup.
Adding lemon.

Boiling water.
Brewing the coffee grounds.
Pouring into cup.
Adding sugar and milk.

Both drinks boiled water and poured into a cup in exactly the same way, because Prepare() in the base class handled that. Only brewing and condiments changed, because those were the steps each subclass was actually responsible for. That's the Template Method pattern.

When to Use it

Use Template Method when several classes share the same overall algorithm, but differ in a few specific steps.

It's a good choice when you want to enforce a fixed sequence of steps, while still letting subclasses customise parts of it.

And it's helpful when you want to avoid duplicating the parts of an algorithm that never change across every subclass.

11. The Visitor Design Pattern

Real World Example

Think of a shopping cart with different kinds of items: books and electronics, each taxed differently at checkout. You don't want to bake pricing logic into the Book and Electronic classes themselves, especially if you'll need other operations on them later too, like generating a shipping label or a warranty summary. Instead, each item just accepts a visitor and hands itself over. The visitor is the one that actually knows how to price a book differently from an electronic.

That's the Visitor pattern. The operation lives outside the objects it acts on, and each object just lets the visitor know what it needs to know: what type of thing it actually is.

Problems it solves:

  • What if pricing logic was written directly inside Book and Electronic? Every new operation (tax, shipping, warranty) would mean editing both classes again and again. The visitor keeps each new operation in its own self-contained class instead.

  • What if you needed to add a new operation without touching the existing item classes? Normally that means modifying every class the operation applies to. A new visitor is a new class, while Book and Electronic never change.

  • What if a generic loop had to guess the concrete type of each item? That usually means a chain of type checks. Accept() calling Visit(this) lets the compiler pick the right overload automatically, without a single if or type check.

In simple terms, you move an operation out of the objects it acts on and into its own class. Each object just accepts a visitor and lets it know what concrete type it is.

Wikipedia describes it like this:

"The visitor design pattern is a way of separating an algorithm from an object structure on which it operates." (Source)

Programming Example:

Book and Electronic both implement IItem and simply call visitor.Visit(this). PricingVisitor implements IVisitor with an overload for each concrete type, so the right pricing logic runs automatically.

// The element interface, every item in the cart implements this
public interface IItem
{
    void Accept(IVisitor visitor);
}

// Concrete elements, each accepts a visitor and hands itself over
public class Book : IItem
{
    public string Title { get; }
    public decimal Price { get; }

    public Book(string title, decimal price)
    {
        Title = title;
        Price = price;
    }

    public void Accept(IVisitor visitor) => visitor.Visit(this);
}

public class Electronic : IItem
{
    public string Name { get; }
    public decimal Price { get; }

    public Electronic(string name, decimal price)
    {
        Name  = name;
        Price = price;
    }

    public void Accept(IVisitor visitor) => visitor.Visit(this);
}

// The visitor interface, one Visit overload per concrete element
public interface IVisitor
{
    void Visit(Book book);
    void Visit(Electronic electronic);
}

// A concrete visitor, adds a new operation without touching Book or Electronic
public class PricingVisitor : IVisitor
{
    public decimal Total { get; private set; }

    public void Visit(Book book)
    {
        Console.WriteLine($"Book: {book.Title} — ${book.Price:F2} (no tax).");
        Total += book.Price;
    }

    public void Visit(Electronic electronic)
    {
        var priceWithTax = electronic.Price * 1.15m;
        Console.WriteLine($"Electronic: {electronic.Name} — ${priceWithTax:F2} (with 15% tax).");
        Total += priceWithTax;
    }
}

Now let's see it in action:

var cart = new List<IItem>
{
    new Book("Design Patterns", 45.00m),
    new Electronic("Headphones", 120.00m)
};

var pricingVisitor = new PricingVisitor();

foreach (var item in cart)
{
    item.Accept(pricingVisitor);
}

Console.WriteLine($"Total: ${pricingVisitor.Total:F2}");

Output:

Book: Design Patterns — $45.00 (no tax).
Electronic: Headphones — $138.00 (with 15% tax).
Total: $183.00

Neither Book nor Electronic contained a single line of pricing logic. Each one only knew how to Accept() a visitor. PricingVisitor was the one that actually decided how each type gets priced. That's the Visitor pattern: the operation lives outside the object structure, not inside it.

When to Use it

Use Visitor when you need to perform operations across a group of unrelated classes, without polluting each class with that logic.

It's also helpful when you want to add new operations often, but the object structure itself rarely changes.

And it's a good choice when you'd otherwise need type checks or casting to figure out what to do with each object in a collection.

Conclusion

That covers all 23 classic design patterns across the three families: Creational, Structural, and Behavioral.

None of them are rules you must follow. They're answers to problems that show up again and again in software: how to create objects without hard-coding their exact type, how to compose bigger structures out of smaller ones, and how to let objects communicate without being tightly bound to each other.

A few things worth remembering:

  • You won't use most of these patterns most of the time. Recognising when a problem calls for one is the actual skill. Forcing a pattern onto a problem that doesn't need it usually makes the code harder to follow, not easier.

  • The real world analogies exist to build intuition, not to be taken literally. Once a pattern's shape clicks in a story you understand, spotting it in real code becomes far easier.

  • Patterns compose. A Factory Method might produce objects that are themselves Decorators. A Composite tree might be built with a Builder. Real systems mix and layer patterns rather than using them in isolation.

  • The language doesn't matter. Every example here is in C#, but the same shapes exist in Python, Java, TypeScript, Go, Rust, and beyond. If you understand the problem a pattern solves, translating it to any language is straightforward.

The goal isn't to memorise 23 names. It's to recognise the recurring problems underneath them, so that when one shows up in your own code, you already know a proven shape for solving it.

"Each pattern describes a problem which occurs over and over again in our environment, and then describes the core of the solution to that problem, in such a way that you can use this solution a million times over, without ever doing it the same way twice."

Source: Christopher Alexander, A Pattern Language — the architectural work that originally inspired software design patterns.

If this handbook was useful, the source lives at github.com/Clifftech123/design-patterns-handbook. Star it, fork it, or open a PR with a pattern you think is missing.

]]> <![CDATA[ How to Understand a Legacy Codebase Using AI Before Changing it ]]> https://www.freecodecamp.org/news/understand-a-legacy-codebase-with-ai/ 6a888892029633fd14697876 Fri, 21 Aug 2026 17:19:14 +0000 The first thing many engineers want to do when they inherit a legacy codebase is change it. And I understand the impulse.

You open a class that's 1,500 lines long. There are database calls mixed with business rules, configuration values scattered across the repository, methods nobody wants to touch, and comments that refer to systems that disappeared years ago.

Then an AI coding assistant offers to explain the whole thing.

So you ask:

Refactor this class.

But that's usually too early.

One of the lessons I've learned from working with legacy systems is that code can be ugly and still contain important knowledge.

A strange condition may encode a business exception. A duplicated calculation may exist because two processes that look identical aren't actually identical. A database column with a terrible name may still be part of an external contract.

And a method nobody understands may be the only thing preventing a production incident that happened eight years ago from happening again.

AI makes it much easier to read unfamiliar software, and that's valuable. But it also makes it much easier to change software before you understand it.

In this tutorial, I'll show you how to use AI for something I believe should happen before refactoring or migration: codebase archaeology.

You'll learn how to use AI to help you:

  • map a repository,

  • identify entry points,

  • trace dependencies,

  • separate business rules from infrastructure,

  • find hidden side effects,

  • inspect data flow,

  • discover implicit contracts,

  • detect duplicated behavior,

  • build a dependency map,

  • identify areas of uncertainty,

  • and turn those findings into a modernization plan.

The examples use TypeScript, but the process works with most languages and stacks.

The goal isn't to ask AI what the code means and trust the answer. The goal is to use AI to reduce the amount of time you spend looking for the right questions.

Prerequisites

You should be comfortable with:

  • reading an existing codebase

  • TypeScript or a similar object-oriented language

  • basic software architecture

  • dependency injection

  • unit and integration testing

  • using an AI coding assistant that can inspect repository files

You don't need a specific AI provider, as the workflow matters more than the model.

Table of Contents

Why Understanding Has to Come Before Refactoring

Legacy code often creates a false sense of urgency.

You see something obviously coupled or duplicated and immediately want to clean it up.

Consider this function:

async function approveOrder(order: Order) {
  if (order.total > 10000 && !order.customer.verified) {
    throw new Error("Manual verification required");
  }

  if (
    order.customer.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    order.status = "PENDING";
  } else {
    order.status = "APPROVED";
  }

  await orders.save(order);

  if (order.status === "APPROVED") {
    await billing.createInvoice(order);
  }

  await audit.log({
    action: "ORDER_APPROVAL",
    orderId: order.id,
    status: order.status,
  });

  return order;
}

At first glance, there are several clear refactoring opportunities:

  • You could extract validation.

  • You could isolate status calculation.

  • You could move billing behind an interface.

  • You could create an approval policy.

All of those ideas may be reasonable, but there are questions you should answer first:

  • Why is 10000 important?

  • Why does an Argentine bank transfer remain pending?

  • Does invoice creation have to happen after persistence?

  • Is ORDER_APPROVAL consumed by another system?

  • Can orders transition from PENDING to APPROVED somewhere else?

  • Does anything depend on the exact exception message?

You can't answer those questions from syntax alone.

That's where understanding begins.

Instead of asking your AI tool:

Refactor this function using clean architecture.

start with:

Analyze this function without changing it.

Identify:

1. explicit business rules,
2. likely business rules that need confirmation,
3. side effects,
4. external dependencies,
5. state transitions,
6. magic values,
7. assumptions that cannot be proven from this file alone.

Do not propose a refactor yet.

That last line is important: Do not propose a refactor yet.

You want the model in investigation mode, not solution mode.

How to Start with the Repository, Not the Classes

When I approach an unfamiliar legacy system, I don't start by reading every file. I start by trying to understand the shape of the application.

A repository already contains architectural clues.

Look for directories such as:

src/
controllers/
services/
repositories/
models/
jobs/
workers/
scripts/
migrations/
config/
integrations/
tests/

But don't assume the directory names describe the real architecture.

A directory called services can contain business logic, infrastructure, orchestration, and random utility functions.

A directory called models might contain database entities rather than domain models.

A folder called utils can hide half the application's business logic.

Use the structure as evidence, not truth.

A useful first AI request is:

Inspect the repository structure.

Do not analyze individual implementation details yet.

Identify:

- application entry points,
- major modules,
- database technologies,
- external integrations,
- background processing,
- scheduled tasks,
- authentication mechanisms,
- configuration sources,
- tests,
- likely architectural boundaries.

For each conclusion, reference the files or directories
that support it.

Mark anything uncertain explicitly.

The requirement to reference files matters. Without it, AI can give you a perfectly reasonable architecture that doesn't actually exist.

You want something closer to:

HTTP API
Evidence:
- src/server.ts
- src/routes/orders.ts
- src/routes/customers.ts

Background processing
Evidence:
- src/workers/paymentWorker.ts
- src/queues/index.ts

Scheduled jobs
Evidence:
- src/jobs/reconcileInvoices.ts
- src/cron.ts

Now you have a map you can verify.

How to Find the Real Entry Points

Web applications often have an obvious HTTP entry point. But legacy systems frequently have several more.

A business operation may begin from:

  • an API request,

  • a scheduled job,

  • a queue consumer,

  • a database trigger,

  • a CLI script,

  • a file import,

  • an email handler,

  • a webhook,

  • or another application calling the database directly.

If you only analyze controllers, you may miss half the system.

Suppose you search for order creation and find:

POST /orders

It would be easy to assume that all orders enter through that endpoint.

Then you discover:

jobs/importMarketplaceOrders.ts
workers/retryFailedOrders.ts
scripts/migratePendingOrders.ts
integrations/shopify/webhook.ts

Now the same business object has four additional entry paths.

This changes how you think about refactoring.

Ask AI:

Find every location that can create, modify,
approve, cancel, or persist an Order.

Include:

- HTTP endpoints,
- background workers,
- scheduled jobs,
- scripts,
- imports,
- webhooks,
- direct repository calls.

Group the results by operation.

For every result, include the file path and
the relevant function or class.

Then verify those results with repository search.

For example:

rg "orders\.save|orders\.insert|createOrder|approveOrder" src

AI should accelerate search, not replace it.

How to Trace a Business Capability Through the Codebase

Understanding individual files isn't enough.

What usually matters is understanding a business capability.

For example:

Create an order.

That capability may travel through several layers:

HTTP Request
     ↓
Controller
     ↓
Application Service
     ↓
Pricing
     ↓
Inventory
     ↓
Persistence
     ↓
Payment
     ↓
Notification

The code may not be organized that cleanly, and that's precisely why tracing the capability is useful.

Choose one real workflow and ask:

Trace the "Create Order" capability from its entry point
until all observable side effects are complete.

For each step, show:

- file,
- function or class,
- input,
- output,
- state change,
- external call,
- error behavior.

Do not summarize multiple steps into one.

You want a sequence that you can inspect.

For example:

1. POST /orders
   src/routes/orders.ts

2. OrdersController.create()
   src/controllers/OrdersController.ts

3. OrderService.create()
   src/services/OrderService.ts

4. calculatePrice()
   src/services/pricing.ts

5. inventory.reserve()
   src/integrations/inventory.ts

6. ordersRepository.save()
   src/repositories/orders.ts

7. paymentQueue.publish()
   src/queues/payment.ts

This becomes far more useful than a generic explanation of the architecture.

Now you can ask questions such as:

  • Where does the transaction actually begin?

  • What happens if payment publishing fails?

  • Is inventory reservation reversible?

  • Can the order be saved twice?

  • Which steps are synchronous?

  • Which failures are retried?

Those are modernization questions.

How to Separate Business Rules from Infrastructure

One of the most useful things you can do during codebase archaeology is identify where business behavior lives.

Legacy applications frequently mix it with infrastructure.

Consider:

async function saveCustomer(customer: Customer) {
  if (
    customer.type === "ENTERPRISE" &&
    customer.creditLimit < 50000
  ) {
    throw new Error("Invalid enterprise credit limit");
  }

  const connection = await mysql.getConnection();

  await connection.query(
    "INSERT INTO customers (...) VALUES (...)",
    [...]
  );

  await redis.del(`customer:${customer.id}`);

  await eventBus.publish(
    "customer.updated",
    customer
  );
}

There's at least one business rule:

Enterprise customers must have a credit limit >= 50000.

And several infrastructure concerns:

MySQL
Redis
Event bus

Ask AI to classify the code:

Classify each responsibility in this function as one of:

- business rule,
- application orchestration,
- persistence,
- caching,
- messaging,
- logging,
- validation,
- unknown.

Explain why.

Do not move or rewrite any code.

The unknown category is useful. You don't want the model to force every line into a clean architectural theory.

Some code really is ambiguous until you inspect more context.

How to Find Hidden Side Effects

Side effects are one of the biggest sources of migration risk.

A function called:

updateCustomer()

may do much more than update a customer.

It may:

  • write to the database

  • invalidate cache

  • emit an event

  • send an email

  • update analytics

  • write an audit record

  • schedule another job

If you refactor the function and preserve only its return value, you can break production behavior without any compiler error.

A useful investigation prompt is:

List every observable side effect produced directly
or indirectly by this function.

For each one, identify:

- the side effect,
- where it happens,
- whether it is synchronous or asynchronous,
- whether failure propagates,
- whether it appears retryable,
- whether it is idempotent,
- whether it can be safely repeated.

Mark uncertain answers as unknown.

That last property, idempotency, matters a lot.

Suppose a worker does this:

await chargeCard(order);
await markOrderAsPaid(order);

If the worker crashes between those two lines and retries, what happens? You may charge the customer twice. And that's not visible from the function name.

Understanding retry semantics is part of understanding the codebase.

How to Discover Implicit Contracts

Not every contract is declared with an interface. Legacy applications contain many implicit contracts.

For example:

return {
  status: "ok",
  value: customer.balance.toFixed(2),
};

Some external consumer may depend on:

{
  "status": "ok",
  "value": "100.00"
}

Changing value from a string to a number can look like an improvement:

{
  "status": "ok",
  "value": 100
}

It can also break a client.

Look for contracts in:

  • API responses,

  • events,

  • database structures,

  • CSV exports,

  • filenames,

  • environment variables,

  • error messages,

  • queue payloads,

  • and webhook bodies.

Ask:

Identify outputs from this module that could be consumed
outside the module.

Include:

- HTTP responses,
- emitted events,
- queue messages,
- files,
- database records,
- exceptions,
- logs used for automated processing.

For each output, explain what evidence suggests that it
may be an external or implicit contract.

The wording matters:

what evidence suggests

not:

tell me which contracts exist

because you may not be able to prove the consumer from the current repository.

How to Use AI to Find Duplicated Business Rules

Duplicated code is easy to detect. Duplicated business meaning is harder.

You may find:

if (customer.type === "PREMIUM") {
  discount = total * 0.1;
}

in one module.

And elsewhere:

if (account.plan === "GOLD") {
  price = price * 0.9;
}

Those might represent the same business rule, or they might not.

AI is useful for identifying candidates.

Ask:

Search the repository for business rules related to
customer discounts.

Group implementations that appear semantically related,
even if variable names differ.

For each group:

- list file locations,
- describe the apparent rule,
- highlight differences,
- do not assume the rules should be unified.

That final instruction is important.

Duplication is sometimes accidental.

Sometimes it represents two domains that evolved independently.

Don't let an AI assistant turn:

similar

into:

must be merged

without evidence.

How to Build a Lightweight Dependency Map

At some point, you need to understand which parts of the system depend on which others.

You don't need a perfect enterprise architecture diagram. A lightweight dependency map is enough to start.

For example:

Orders
 ├── Customers
 ├── Inventory
 ├── Payments
 ├── Notifications
 └── Database

Payments
 ├── Payment Provider
 ├── Audit
 └── Database

Ask AI to extract module-level dependencies:

Build a module dependency map from the repository.

Only include dependencies supported by imports,
constructor dependencies, explicit calls, or configuration.

Output:

Module A -> Module B

For each dependency, provide at least one source file
that demonstrates it.

Do not infer dependencies from names alone.

You can then compare the result with automated tools.

For JavaScript or TypeScript projects, dependency analysis tools can help you find:

  • circular dependencies

  • cross-module imports

  • high fan-in

  • high fan-out

AI is useful for explaining why those dependencies may matter. Static analysis is better at proving that they exist.

Use both.

How to Mark What You Still Do Not Understand

This is one of the most important parts of the process.

A useful system map doesn't only contain answers. It also contains uncertainty.

I like keeping an explicit list such as:

## Open Questions

- Why is the enterprise credit threshold 50,000?
- Is `ORDER_APPROVAL` consumed outside this repository?
- Can marketplace orders bypass inventory validation?
- Is `customer.balance` allowed to be negative?
- What process transitions PENDING orders to APPROVED?
- Is `legacy_customer_id` still used by another system?

You can ask AI to generate this list:

Based on everything analyzed so far, list the questions
that can't be answered safely from the repository.

Focus on questions that would matter during:

- refactoring,
- migration,
- schema changes,
- interface changes,
- removal of code.

Do not answer the questions.

I like this prompt because it does the opposite of what we normally ask AI to do. It asks the model to identify where it should not pretend to know.

A modernization plan should include those unknowns.

How to Validate AI Findings Against the System

AI-generated explanations can sound convincing even when they're incomplete. So every important finding should have another source of evidence.

I use a simple hierarchy.

If AI says a function is called only once, search for it.

rg "approveOrder" .

Tests

Tests often reveal assumptions that implementation code doesn't explain.

Look for:

expected errors
special values
boundary cases
fixture data
historical behavior

Database Schema

The schema may reveal key things like:

  • nullable fields

  • foreign keys

  • defaults

  • legacy columns

  • constraints

  • status values

Logs and Observability

Production telemetry can tell you whether a supposedly unused path is still active.

Version History

Git history can sometimes answer questions that source code can't.

For example:

git log -S "Manual verification required" --all

or:

git blame src/orders/approveOrder.ts

The commit that introduced a strange condition may contain the explanation.

This is an area where AI can help summarize history:

Review the commits that changed this function.

Build a timeline of behavior changes.

For each change, include:

- commit,
- date,
- behavior changed,
- stated reason if available.

Do not infer a reason if the commit history does not provide one.

That can save a surprising amount of time.

How to Turn Codebase Understanding into a Migration Plan

Once you understand one capability, you can begin making decisions. But not before.

Suppose your investigation produces this:

Create Order

Business rules:
- active customer required
- premium customers receive 10% discount
- inventory must be available

Side effects:
- order persisted
- inventory reserved
- payment queued
- confirmation email sent

External contracts:
- POST /orders response
- payment queue payload
- order.created event

Unknowns:
- retry semantics for inventory reservation
- whether event consumers require exact field names

Now you can decide what to protect.

For example:

Protect first:
- pricing behavior
- API response
- payment payload
- event schema

Then decide what can be refactored.

Candidate boundaries:
- pricing policy
- inventory gateway
- payment publisher
- notification service

Then decide what needs investigation.

Block migration until understood:
- inventory retry behavior
- event consumers

That's already a migration plan.

Notice what AI did not do: it didn't decide the target architecture.

It helped make the current architecture observable enough for you to make that decision.

A Practical Codebase Archaeology Workflow

If I had to reduce this process to something repeatable, I would use these steps.

1. Map the Repository

Identify:

  • entry points

  • modules

  • persistence

  • integrations

  • workers

  • jobs

  • tests

  • configuration

Don't refactor anything.

2. Choose One Capability

Pick something concrete:

Create Order
Approve Loan
Generate Invoice
Register Customer
Cancel Subscription

Avoid trying to understand the whole product at once.

3. Trace It End to End

Follow:

input
↓
business logic
↓
state changes
↓
external calls
↓
output

Record every file involved.

4. Extract Business Rules

Separate:

  • explicit rules

  • likely rules

  • infrastructure behavior

  • unknowns

5. Identify Side Effects

Find:

  • writes

  • messages

  • emails

  • jobs

  • cache changes

  • external calls

6. Discover Contracts

Look for:

  • APIs

  • event schemas

  • database assumptions

  • exported files

  • error behavior

7. Map Dependencies

Document:

module -> module

and identify coupling.

8. Record Unknowns

Don't hide uncertainty. Create an explicit list.

9. Verify

Use:

  • repository search

  • tests

  • schema

  • logs

  • Git history

  • production telemetry

10. Only Then Plan the Change

Decide:

  • what behavior must survive,

  • what code can disappear,

  • what boundaries should be introduced,

  • what needs tests,

  • and what can migrate first.

What I Would Not Ask AI to Do First

There are several prompts I avoid at the beginning of a legacy modernization project.

For example:

Rewrite this application using Clean Architecture.

or:

Convert this monolith into microservices.

or:

Modernize this entire repository.

or even:

Find all the bad code.

The problem isn't that AI can't produce useful output from those prompts. It can.

The problem is that those questions already contain a solution.

You're asking for:

Clean Architecture
Microservices
Rewrite
Bad code

before you've established what the system actually needs.

A better sequence is:

What exists?
↓
Why does it exist?
↓
What behavior matters?
↓
What is uncertain?
↓
What should change?

That sequence is slower for the first hour, but it's usually much faster for the rest of the project.

The Most Useful AI Output Is Sometimes a Question

There's a tendency to evaluate AI coding tools by how much code they generate.

For legacy systems, I think that misses part of their value.

One of the most useful outputs can be:

I cannot determine why this condition exists from the available code.

Or:

This event appears to have no consumer in the current repository, but external consumers cannot be ruled out.

Or:

These two discount calculations look similar, but their behavior differs for zero-value orders.

Those are useful findings that tell an engineer where to investigate.

A confident but incorrect answer is much more dangerous.

When working with legacy systems, uncertainty is information. Treat it that way.

Conclusion

AI makes unfamiliar codebases much easier to explore.

You can use it to summarize modules, trace execution paths, extract candidate business rules, find side effects, compare implementations, analyze Git history, and build dependency maps.

That can remove a large amount of mechanical investigation work.

But understanding a system isn't the same as generating an explanation of it. Legacy applications contain context that may exist outside the source code:

  • production behavior,

  • old incidents,

  • external consumers,

  • business exceptions,

  • undocumented integrations,

  • and organizational history.

AI can help you find evidence. It can't manufacture missing history.

That's why I prefer to use it as an investigator before I use it as a transformer.

Start with:

What does this system actually do?

Then ask:

What do I still not understand?

Only after that should you ask:

What should I change?

The faster AI lets you modify software, the more important that sequence becomes.

Because changing code you understand is engineering. But changing code you don't understand is experimentation.

And production is usually the most expensive place to run that experiment.

]]> <![CDATA[ How to Modernize a Legacy Application with AI Without Turning It Into a Rewrite ]]> https://www.freecodecamp.org/news/modernize-legacy-applications-with-ai/ 6a7e4a380ee61c58fa48acb3 Thu, 13 Aug 2026 22:50:32 +0000 I have seen legacy migrations considered successful because the old framework disappeared from the repository.

Six months later, the team was still dealing with the same coupling, the same unclear business rules, and almost the same deployment problems.

The technology had changed but the system hadn't changed very much as a whole.

AI makes this problem even more interesting.

It can translate code faster than a team could do manually. It can explain unfamiliar classes, generate tests, create adapters, update APIs, and remove a significant amount of repetitive work.

But if you point an AI coding tool at an old application and simply ask it to migrate everything to a modern stack, there's a good chance you'll get exactly what you asked for: the same system, rewritten faster.

That's not necessarily modernization.

In this tutorial, I want to show you a different way to use AI during a legacy migration.

Instead of treating AI as an automated code translator, you'll use it to help you:

  • understand an unfamiliar codebase,

  • identify business rules and hidden dependencies,

  • build a behavioral safety net,

  • find boundaries for incremental migration,

  • refactor before replacing,

  • automate repetitive transformations,

  • compare old and new behavior,

  • and detect regressions before they reach production.

The examples use TypeScript, but the process itself isn't tied to TypeScript or Node.js.

The important part is the workflow. AI can make migration work faster. But Engineering still has to decide what's worth migrating.

Prerequisites

You should be comfortable with:

  • basic TypeScript,

  • unit and integration testing,

  • dependency injection,

  • software architecture concepts,

  • and working with an existing codebase.

The examples use Vitest, but the same ideas apply if you use Jest or another testing framework.

Table of Contents

How to Avoid a One-to-One Legacy Migration

Imagine that you find this function in an old order-processing system:

async function processOrder(order: Order) {
  if (!order.customer.active) {
    throw new Error("Inactive customer");
  }

  const discount =
    order.customer.type === "PREMIUM"
      ? order.total * 0.1
      : 0;

  const finalAmount = order.total - discount;

  await db.orders.insert({
    customerId: order.customer.id,
    amount: finalAmount,
  });

  await paymentGateway.charge(
    order.customer.card,
    finalAmount,
  );

  await mailer.send(
    order.customer.email,
    "Order processed",
  );

  return finalAmount;
}

The function works, but it also does quite a lot.

It validates the customer, applies a pricing rule, persists data, charges a payment method, and sends a notification.

A one-to-one migration might turn this into a prettier TypeScript service with newer libraries while keeping all those responsibilities together.

You might replace an old controller with a new controller, an old service with a new service, and an old ORM with a new ORM...and still preserve the same architectural problem.

This is one of the first places where AI can work against you.

If your prompt is:

Convert this legacy class to TypeScript.

the model will normally preserve the structure because preserving the structure is the task you gave it.

Before asking AI to transform code, separate two questions:

  1. What behavior must survive?

  2. What design should survive?

Those aren't the same question.

Sometimes an implementation is old but its behavior is still essential. Sometimes the behavior matters but the implementation should disappear. And sometimes you discover that neither needs to survive.

That distinction should happen before the bulk migration begins.

How to Map a Legacy Codebase Before Changing It

The first difficult part of a legacy migration is usually understanding what you actually have.

Documentation helps when it exists. But in many systems, the real documentation is distributed across:

  • conditional statements,

  • database constraints,

  • scheduled jobs,

  • comments,

  • logs,

  • integration code,

  • tests,

  • configuration,

  • and knowledge that lives in people's heads.

This is an area where AI can save time without being asked to make architectural decisions.

Take the previous processOrder function. Instead of asking AI to rewrite it, start with questions such as:

Identify the business rules in this function.

List every side effect.

Which external systems does it depend on?

Which parts could be expressed as pure functions?

Which observable behaviors should probably be protected
with tests before this function is changed?

Do not rewrite the function.

The last instruction matters more than it may seem.

When analysis and transformation happen in the same request, it becomes easy for an AI tool to solve a design problem you haven't fully understood yet.

I prefer to make the analysis explicit first.

For a larger codebase, repeat the process at several levels.

At repository level, look for:

  • entry points,

  • database access,

  • external APIs,

  • message queues,

  • background jobs,

  • scheduled tasks,

  • configuration,

  • shared state,

  • authentication,

  • and authorization.

At module level, look for:

  • business rules,

  • dependencies,

  • side effects,

  • duplicated logic,

  • highly coupled classes,

  • and implicit contracts.

At function level, look for:

  • inputs,

  • outputs,

  • exceptions,

  • state changes,

  • external calls,

  • and edge cases.

AI can make this exploration much faster. But its findings should be checked against the actual repository, tests, schema, logs, and production behavior.

A confident explanation of the code is still only an explanation. The repository remains the source of truth.

How to Build Characterization Tests Before Refactoring

One of the uncomfortable parts of legacy software is that strange behavior is not necessarily accidental.

You may find code that looks obviously wrong and discover later that another part of the business depends on it.

This is where characterization tests are useful.

Michael Feathers discusses this approach in Working Effectively with Legacy Code: instead of beginning by describing how the system should behave, you first capture how it behaves today.

Consider this function:

export function calculateDiscount(
  customerType: string,
  total: number,
): number {
  if (customerType === "PREMIUM") {
    return total * 0.1;
  }

  return 0;
}

You can protect its current behavior with tests:

import { describe, expect, it } from "vitest";
import { calculateDiscount } from "./calculateDiscount";

describe("calculateDiscount", () => {
  it("applies a 10 percent discount to premium customers", () => {
    expect(
      calculateDiscount("PREMIUM", 100),
    ).toBe(10);
  });

  it("does not discount regular customers", () => {
    expect(
      calculateDiscount("REGULAR", 100),
    ).toBe(0);
  });

  it("returns zero when the order total is zero", () => {
    expect(
      calculateDiscount("PREMIUM", 0),
    ).toBe(0);
  });
});

AI is useful for expanding this safety net.

For example:

Generate characterization tests for this function.

Preserve the existing behavior.

Include:
- normal inputs,
- boundary values,
- invalid inputs,
- exceptions,
- observable side effects.

Do not redesign the function.

Then review what it generates.

You aren't proving that the old behavior is correct. You're recording what will change if you refactor it.

That difference matters.

If a test captures a behavior you later decide is a bug, change it intentionally. What you want to avoid is changing behavior accidentally and discovering the difference after deployment.

How to Find Safe Migration Seams

Legacy applications rarely need to be replaced all at once.

They usually need places where the old and new systems can coexist temporarily.

Feathers also describes the idea of a seam in Working Effectively with Legacy Code: a place where you can alter behavior without having to modify everything around it.

The order-processing example gives you one possible seam.

The original function contains:

  • customer validation,

  • discount calculation,

  • database persistence,

  • payment processing,

  • and email notification.

The first two belong naturally to business behavior. The others involve infrastructure. That suggests a possible boundary.

Domain/application responsibilities:

  • customer rules,

  • pricing rules,

  • order workflow.

Infrastructure responsibilities:

  • database,

  • payment provider,

  • email provider.

AI can help identify candidates for these boundaries.

For example:

Analyze these files and identify:

- business rules,
- infrastructure concerns,
- side effects,
- shared mutable state,
- duplicated logic,
- dependencies that make isolated testing difficult.

Suggest possible boundaries.

Do not rewrite the code yet.

Again, the AI output is input to an engineering decision. It shouldn't become the decision automatically.

When you find a good seam, you gain a place where modernization can progress without requiring a rewrite of the entire application.

How to Refactor Toward Explicit Responsibilities

Once you understand a section of the code and have tests around its current behavior, refactoring becomes less dangerous.

The pricing rule can become a pure function:

export function calculateDiscount(
  customerType: string,
  total: number,
): number {
  if (customerType === "PREMIUM") {
    return total * 0.1;
  }

  return 0;
}

Customer validation can be separated:

export function validateCustomer(
  customer: Customer,
): void {
  if (!customer.active) {
    throw new Error("Inactive customer");
  }
}

Infrastructure can move behind contracts:

export interface OrderRepository {
  save(order: PersistedOrder): Promise<void>;
}

export interface PaymentGateway {
  charge(
    card: string,
    amount: number,
  ): Promise<void>;
}

export interface NotificationService {
  sendOrderConfirmation(
    email: string,
  ): Promise<void>;
}

The application workflow becomes easier to read:

export class ProcessOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly payments: PaymentGateway,
    private readonly notifications: NotificationService,
  ) {}

  async execute(order: Order): Promise<number> {
    validateCustomer(order.customer);

    const discount = calculateDiscount(
      order.customer.type,
      order.total,
    );

    const finalAmount =
      order.total - discount;

    await this.orders.save({
      customerId: order.customer.id,
      amount: finalAmount,
    });

    await this.payments.charge(
      order.customer.card,
      finalAmount,
    );

    await this.notifications.sendOrderConfirmation(
      order.customer.email,
    );

    return finalAmount;
  }
}

There's nothing particularly revolutionary in this refactoring. That's part of the point.

Modernization doesn't require an exotic architecture.

Often the important improvement is simply making responsibilities explicit enough that the next change doesn't require understanding the entire application.

How to Use AI for Mechanical Transformations

Once the boundaries are clear, AI becomes much more useful for implementation.

A surprising amount of migration work is necessary but repetitive:

  • translating APIs,

  • replacing framework conventions,

  • generating adapters,

  • converting configuration,

  • updating type definitions,

  • changing data access libraries,

  • and updating repetitive integration code.

These are good places to use AI.

Imagine that the old system performs SQL directly:

async function getCustomer(id: number) {
  const result = await db.query(
    `SELECT * FROM customer WHERE id = ${id}`,
  );

  return result[0];
}

Before generating the new implementation, define the contract you want:

export interface CustomerRepository {
  findById(id: number): Promise<Customer | null>;
}

Then constrain the transformation:

Implement CustomerRepository using the new database client.

Constraints:

- Keep the CustomerRepository interface unchanged.
- Use parameterized queries.
- Do not move business rules into the repository.
- Preserve the existing null behavior.
- Preserve the existing error semantics.
- Return only the implementation.

This is a very different request from:

Modernize this database code.

In the first case, you made the architectural decision and asked AI to implement within that boundary.

That is where I find AI most useful in migration work. It removes mechanical effort after the important decisions have already been made.

How to Migrate in Small Vertical Slices

Large migrations become difficult to reason about when thousands of files change together.

A safer unit of change is often a business capability.

Instead of migrating all controllers, then all services, and finally all repositories, migrate one complete capability.

For example:

Create Order

  • API

  • application logic

  • domain rules

  • persistence

  • tests

Then move to the next capability.

This has several advantages. First, the migration remains closer to deployable software. Second, the context you give an AI tool stays smaller.

Testing also becomes more focused. And if something goes wrong, the failure is easier to isolate.

A useful first prompt for a vertical slice is analysis-only:

We are migrating the Create Order capability.

The legacy implementation is under /legacy/orders.

The target architecture separates:
- domain,
- application,
- infrastructure.

The characterization tests under /tests/legacy
describe behavior that must remain compatible.

Analyze the current implementation.

List:
1. business rules,
2. external dependencies,
3. side effects,
4. likely migration risks,
5. files that need to change.

Do not generate code yet.

Review that output, then plan the actual transformation.

This is also compatible with an incremental replacement strategy such as Martin Fowler's Strangler Fig approach, where new functionality gradually takes over from an older system instead of requiring one large cutover.

The important word is gradually.

AI can increase transformation speed. That doesn't make a big-bang migration less risky.

How to Compare Legacy and Modern Behavior

Unit tests give you one kind of safety.

For a migration, I also like comparing the old and new implementations directly.

Suppose both systems can process the same order. You can run the same fixture through each one:

const inputs = [
  premiumCustomerOrder,
  standardCustomerOrder,
  inactiveCustomerOrder,
];

for (const input of inputs) {
  const legacyResult =
    await legacyProcessor(input);

  const modernResult =
    await modernProcessor(input);

  expect(modernResult).toEqual(legacyResult);
}

This is a simple form of differential testing. You can do the same thing at the HTTP boundary.

Send the same POST /orders request to both versions and compare:

  • status codes

  • response payloads

  • database changes

  • emitted events

  • external calls

  • errors

An important point: a difference isn't automatically a bug. Sometimes behavior is supposed to change. The useful thing is making the difference visible so someone has to classify it deliberately.

AI can help here too.

If you have hundreds of mismatches, you can ask it to group them:

Analyze these behavioral mismatches.

Group them by likely cause.

Pay particular attention to:
- rounding,
- null handling,
- timezone conversion,
- validation,
- serialization,
- data mapping.

Do not label a mismatch as a defect unless the
available evidence supports that conclusion.

This is a good use of AI because the model is reducing investigation work. It's not deciding whether production behavior is acceptable.

How to Use Shadow Traffic to Find Regressions

Eventually, test fixtures stop being representative enough.

Production systems receive combinations of inputs nobody thought to put into a test suite.

One way to observe those differences is shadow traffic. The legacy application continues serving the user's request, and a copy of that request also goes to the new implementation. The new result is used for comparison only and isn't returned to the user.

For example:

Legacy:
200
{ "total": 90 }

Modern:
200
{ "total": 90 }

MATCH

Or:

Legacy:
200
{ "total": 90 }

Modern:
200
{ "total": 100 }

MISMATCH

Collecting those mismatches gives you evidence about how the new system behaves under real traffic without immediately exposing users to it.

This technique comes with operational considerations. You need to think carefully about:

  • duplicated side effects,

  • payment calls,

  • emails,

  • writes,

  • privacy,

  • production load,

  • and external API usage.

A shadow instance should generally avoid performing irreversible side effects.

For example, replace the real payment adapter with a recording adapter:

export class RecordingPaymentGateway
  implements PaymentGateway {

  public readonly calls: Array<{
    card: string;
    amount: number;
  }> = [];

  async charge(
    card: string,
    amount: number,
  ): Promise<void> {
    this.calls.push({
      card,
      amount,
    });
  }
}

Now you can compare the intention to charge without charging a customer twice.

How to Test the Architecture You Actually Want

Behavioral compatibility isn't enough if one objective of the migration is improving the architecture.

Imagine that you've decided on this constraint:

Domain code must not depend on infrastructure code.

If that rule only exists in an architecture diagram, migration pressure will eventually break it.

So test it.

For a simple project, you can inspect imports. For a larger one, use a dependency-analysis tool capable of enforcing architectural rules.

The exact tooling matters less than the principle:

If an architectural constraint matters, make breaking it visible.

You may want rules such as:

  • domain must not depend on infrastructure

  • domain must not depend on the HTTP framework

  • application code must not depend directly on the database driver

  • modules must not import another module's internal implementation

Why does this matter in an AI-assisted migration? Because AI is very good at finding a way to make code compile.

If reaching directly into another module solves the immediate problem, generated code may do exactly that unless the boundary is part of the constraints.

Architecture tests give both humans and AI tooling a harder boundary to violate accidentally.

How to Decide Which Tasks AI Should Handle

I don't treat all migration tasks equally. Some are good candidates for automation.

Tasks Where AI Is Usually Useful

  • explaining unfamiliar code

  • identifying dependencies

  • extracting candidate business rules

  • generating characterization test cases

  • generating repetitive adapters

  • updating framework APIs

  • translating mechanical code

  • creating migration checklists

  • comparing implementations

  • classifying regression output

  • drafting technical documentation

Tasks Where I Want Significant Engineering Review

  • proposing module boundaries

  • extracting domain concepts

  • refactoring highly coupled classes

  • choosing migration sequences

  • changing data models

  • designing integration boundaries

Decisions I Would Keep Under Human Ownership

  • target architecture

  • acceptable behavioral differences

  • security boundaries

  • data migration strategy

  • rollout strategy

  • rollback strategy

  • removal of legacy behavior

  • production risk acceptance

This isn't because AI can't produce an architecture proposal. It can.

The problem is accountability and context.

Architecture choices are consequences of constraints, history, organizational capabilities, business priorities, and operational risks that may not exist anywhere in the repository.

A model can help you explore those choices, but someone still has to own them.

How to Measure Whether the Migration Actually Improved the System

Migration velocity is an attractive metric because it's easy to show.

For example:

37% of the codebase migrated.

That doesn't tell you much about whether the system became better.

A modernization effort should look at several kinds of outcomes. Operational metrics might include:

  • deployment frequency

  • change failure rate

  • mean time to recovery

  • production incidents

  • build time

Engineering metrics might include:

  • test coverage

  • high-complexity classes

  • duplicated business rules

  • cross-module dependencies

  • architectural violations

  • time required to change a capability

Migration-specific metrics might include:

  • regression rate

  • percentage of traffic handled by the new path

  • unresolved behavioral mismatches

  • rollback frequency

  • legacy components still in use

The exact metrics depend on the system. What matters is avoiding this definition of success:

Old repository is smaller = modernization succeeded.

AI makes it possible to transform more code in less time. That makes measuring the quality of the transformation more important, not less.

The Risk I Worry About Most with AI-Assisted Migration

Hallucinated code is a clear risk. But I worry more about plausible code.

Generated code can compile. It can look cleaner than the original implementation. It can even pass a shallow test suite. And it can still subtly change a business rule that nobody realized existed.

Consider something as small as:

if (customer.balance > 0) {
  charge(customer);
}

It's tempting to clean up code when you don't understand why a condition exists.

But maybe zero has a special business meaning.

Maybe negative balances are legitimate.

Maybe the condition was introduced after a production incident six years ago and never documented.

AI can't recover context that doesn't exist in the information available to it. This is why I put so much emphasis on characterization tests and behavioral comparison.

The faster the transformation becomes, the stronger the validation process needs to become.

Otherwise, you're only increasing the speed at which you can introduce unknown changes.

A Practical Migration Workflow

If I had to reduce the process to one repeatable sequence, I would use this.

1. Understand

Map:

  • behavior

  • dependencies

  • business rules

  • side effects

  • data

  • integrations

Use AI to accelerate the investigation. Don't start by generating the new system.

2. Protect

Build:

  • characterization tests

  • integration tests

  • API fixtures

  • behavioral snapshots

Make current behavior observable.

3. Design

Choose:

  • boundaries

  • interfaces

  • responsibilities

  • migration seams

Do this before large-scale transformation.

4. Refactor

Create enough separation that part of the system can move without dragging everything else with it.

5. Transform

Use AI heavily for repetitive implementation work.

Give it explicit architectural constraints.

6. Compare

Run old and new behavior against the same inputs and investigate differences.

7. Release Gradually

Use the mechanisms appropriate for your environment:

  • feature flags

  • canary deployments

  • shadow traffic

  • observability

  • rollback

8. Remove the Old Path

Don't leave both systems running indefinitely. A migration that never removes the legacy path eventually creates another legacy architecture.

Conclusion

AI changes the economics of legacy modernization.

A lot of work that used to consume engineering hours can now happen much faster: reading unfamiliar code, generating tests, updating APIs, translating repetitive implementations, and investigating differences between systems.

That's useful. But it's not the part of modernization that requires the most judgment.

The difficult questions remain:

  • What behavior still matters?

  • What should disappear?

  • Which dependencies should survive?

  • Where should the boundaries be?

  • How much behavioral change is acceptable?

  • When is the new implementation safe enough to receive production traffic?

If you use AI only to translate code, you can migrate technical debt faster.

If you combine it with characterization testing, incremental refactoring, explicit architectural boundaries, differential testing, and controlled rollout, you have a better chance of improving the system while you move it.

The objective isn't to move the same system onto a newer stack. It's to understand it, protect its important behavior, refactor it, migrate it incrementally, validate the result, and end up with a simpler system than the one you started with.

AI can shorten that path. But it still can't decide what the destination should be.

]]> <![CDATA[ Flutter Frontend Systems Design: How to Think Like a Senior Engineer in the AI Age ]]> https://www.freecodecamp.org/news/flutter-frontend-systems-design-how-to-think-like-a-senior-engineer-in-the-ai-age/ 6a79dcd1e93f9db759fd99d6 Mon, 10 Aug 2026 14:14:41 +0000 Systems design has always been treated as a backend problem.

Ask a group of Flutter engineers what systems design means, and most will describe server architecture: load balancers, databases, and microservices.

Ask them to design a distributed cache or sketch out a message queue, and they'll hesitate. Ask them to design the Flutter client for a social feed, and they'll open a new file and start writing widgets.

That's the gap. And it's closing fast.

As Flutter applications grow more complex with real-time features, offline support, multiple platform targets, and AI-generated code that still needs to be maintainable, the architectural decisions you make before writing a single widget become just as important as your backend architecture.

Senior Flutter interviews at product companies increasingly test this skill. The engineers who can clearly explain why they chose a particular architecture, the trade-offs they considered, and the problems they were optimizing for are the ones who get hired and promoted.

This article is structured in two halves. The first half explains what frontend systems design actually is and why it matters for Flutter engineers specifically in 2026. The second half works through a full mock interview answer for one of the most common scenario questions: designing the Flutter architecture for a social feed with infinite scroll, likes, comments, and real-time updates. We'll walk through the kind of answer that separates mid-level from senior in an interview room.

Prerequisites

This article assumes you're a working Flutter developer comfortable with state management (Riverpod, Bloc, or similar), REST APIs, and basic Dart. You don't need backend experience, but familiarity with concepts like caching, pagination, and WebSockets will help you follow the deeper sections.

No code setup is required. This is a thinking and architecture article, not a tutorial. Dart/Flutter snippets are used to ground abstract ideas in concrete implementation.

Table of Contents

1. What is Frontend Systems Design?

Systems design is the practice of making high-level decisions about how a software system is structured before implementation begins: how its components are divided, how they communicate, how it handles scale, failure, and change over time.

On the backend, this means deciding between microservices and a monolith, choosing a database, designing an API contract, and planning for horizontal scaling. The feedback loop is fast: a bad database schema causes slow queries within days, and a poorly designed API breaks clients immediately.

On the frontend, the consequences of bad design are slower and quieter. A 600-line screen widget still ships. A god-class repository with 40 methods still works. State leaks between sessions only surface after a frustrated user reports it.

Frontend systems design asks the same category of questions, applied to the client layer:

  • How do you divide a large app into independently-buildable features?

  • Where does business logic live, and what enforces that boundary?

  • How does data flow from the network to the screen and back?

  • What happens when the network fails, the API changes shape, or the user logs out mid-session?

  • How do you design components that can be tested in isolation?

  • How do you structure the app so a team of engineers can work on it without stepping on each other?

These aren't widget questions. They're architecture questions. And they have answers: principled ones, with real tradeoffs.

2. Why Flutter Engineers Can't Ignore It Anymore

Three forces are pushing systems design into the Flutter conversation in a way that simply didn't exist three years ago.

Flutter Apps Are No Longer Just UIs

With Serverpod and Dart Frog on the server, Jaspr on the web, and Flutter on mobile and desktop, Dart is now a genuinely full-stack language. Engineers making architecture decisions that span mobile, web, and server in the same codebase need systems thinking, not just widget composition skills.

When your Freezed model is shared between the Flutter client and the Dart backend, the boundary between "frontend" and "backend" design dissolves. You're designing a system.

AI Agents Expose Bad Architecture Immediately

This is the new pressure point. When Claude Code or any AI coding agent reads your project cold, it has no accumulated mental model to compensate for messiness. It reads files sequentially. It works within a limited context window. It makes decisions based on the patterns it sees.

A codebase with tangled dependencies, inconsistent naming, and business logic scattered across the widget tree produces unreliable AI output. This doesn't happen because the AI is wrong, but because the code doesn't communicate its own structure clearly enough to be navigated by something without human intuition.

Good systems design and AI-navigable architecture are almost identical. Feature-first structure, clear layer boundaries, consistent naming, small, focused files. These aren't just team hygiene practices anymore. They're what make AI-assisted development actually work at scale.

Senior Flutter Interviews Now Test it Explicitly

As Flutter matures and product companies build larger apps with larger teams, the interview bar has risen. A mid-level Flutter interview might test widget lifecycle and state management fundamentals. A senior interview tests your ability to design a system you've never seen before, live, under pressure, while explaining your thinking out loud.

If you haven't thought about this before walking into that room, you'll be caught off guard.

3. The Interview Format: What to Expect

Frontend systems design interviews at senior level typically run 45–60 minutes. You're given a vague scenario, like "design the Flutter client for a social feed", and you're expected to drive the conversation.

The interviewer isn't looking for a single correct answer. They're watching how you think:

  • Do you clarify requirements before jumping to solutions?

  • Do you identify the hard problems (real-time sync, optimistic UI, offline states) rather than the easy ones?

  • Do you make tradeoffs explicitly rather than just picking the thing you know best?

  • Can you go deep on any layer when pushed?

The biggest mistake candidates make is opening Xcode or a code file immediately and starting to build. Systems design interviews are whiteboard conversations, not implementation sessions. Draw boxes. Name the layers. Talk through the data flow before writing a single method signature.

4. How to Structure Your Answer

Use this framework for any frontend systems design question:

  1. Clarify requirements (5 minutes) What platforms? How many users? Offline support? Real-time? Authentication? What's in scope for this conversation? Never assume.

  2. Define the data model (5–10 minutes) What are the core entities? What are their relationships? This anchors every architectural decision that follows.

  3. Design the layer architecture (10 minutes) How is the app divided? What are the layers? What enforces the boundaries between them?

  4. Solve the hard problems one by one (20–25 minutes) Pagination. Optimistic UI. Real-time sync. Offline. Performance. Go deep on each one, and name the tradeoffs.

  5. Address failure states (5 minutes) What breaks? What's the user experience when it does? Senior answers always include error handling.

  6. Summarise and invite questions (5 minutes) Recap the key decisions and the tradeoffs you made. Show you can hold the whole picture.

5. Mock Interview: Design a Social Feed

Interviewer: Design the Flutter client architecture for a social feed. Users can scroll through posts, like and comment on them, and receive real-time updates when new posts arrive.

This is the answer.

Step 1: Clarify Requirements

Before touching architecture, ask the questions that constrain your decisions.

"A few questions before I start. What platforms are we targeting? Mobile only, or web and desktop too? How many users are we designing for? Is this a startup MVP or an app at scale? Do we need offline support? How real-time does real-time need to be? Are we talking push notifications, or should the feed update while the user is looking at it? And what's the authentication model? Are users logged in, or is there a guest mode?"

For this walkthrough, assume:

  • Mobile (iOS + Android), with web on the roadmap

  • Tens of thousands of MAU. Not Twitter scale, but meaningful.

  • Offline: show cached content, queue interactions

  • Real-time: live feed updates while the screen is open (WebSocket)

  • Auth: logged-in users only

These answers change every architectural decision that follows. Offline support means a local cache layer. Live updates while the screen is open means WebSockets, not polling. Web on the roadmap means avoiding anything mobile-only in the business logic layer.

Step 2: Define the Data Model

Start with the entities and their relationships. Draw these before writing any code.

// Core entities

@freezed
class Post with _$Post {
  const factory Post({
    required String id,
    required String authorId,
    required String authorName,
    required String authorAvatarUrl,
    required String content,
    String? imageUrl,
    required int likeCount,
    required int commentCount,
    required bool isLikedByMe,      // derived from current user context
    required DateTime createdAt,
  }) = _Post;
}

@freezed
class Comment with _$Comment {
  const factory Comment({
    required String id,
    required String postId,
    required String authorId,
    required String authorName,
    required String content,
    required DateTime createdAt,
  }) = _Comment;
}

@freezed
class FeedPage with _$FeedPage {
  const factory FeedPage({
    required List<Post> posts,
    required String? nextCursor,    // null = end of feed
  }) = _FeedPage;
}

A few design decisions embedded in this model are worth calling out explicitly in an interview:

isLikedByMe lives on the Post. You could derive this from a separate user-likes table, but embedding it in the post response is simpler and makes the UI stateless. The screen doesn't need to join two data sources to render a like button.

Cursor-based pagination, not offset. nextCursor rather than page: 2. Offset pagination breaks when new posts are inserted at the top. Item 20 on page 2 becomes item 21, and you either show a duplicate or skip an item. Cursors are stable.

likeCount and commentCount are integers, not arrays. You don't fetch all likers to render a post. You fetch the count and a flag. This is a deliberate API contract decision that prevents unbounded payload size.

Step 3: Design the Layer Architecture

A feed is a good test of layer discipline because data flows in multiple directions: down from the API, up from user interactions, and sideways from real-time events. A flat architecture collapses quickly.

Here's the structure:

lib/
├── core/
│   ├── network/          # Dio client, interceptors, token refresh
│   ├── cache/            # Local storage abstraction (Hive or Isar)
│   ├── realtime/         # WebSocket connection manager
│   └── errors/           # Typed error classes
└── features/
    └── feed/
        ├── data/
        │   ├── models/   # Post, Comment, FeedPage (Freezed)
        │   ├── sources/
        │   │   ├── feed_remote_source.dart   # API calls
        │   │   └── feed_local_source.dart    # Cache reads/writes
        │   └── repositories/
        │       └── feed_repository.dart      # Coordinates remote + local
        └── presentation/
            ├── screens/
            │   └── feed_screen.dart
            ├── widgets/
            │   ├── post_card.dart
            │   ├── like_button.dart
            │   └── comment_sheet.dart
            └── providers/
                ├── feed_provider.dart        # Paginated post list
                ├── like_provider.dart        # Like/unlike actions
                └── realtime_provider.dart    # WebSocket events → state

A couple things worth noting here:

First, the repository is the only component that talks to both the remote source and the local source. Providers call the repository. The repository decides whether to hit the network or return cached data. Screens never know the data came from cache.

Second, the real-time layer is separate from the data fetching layer. It's a common mistake to wire WebSocket events directly into the same provider that manages pagination, and it becomes impossible to test or reason about. The realtime_provider receives events and patches the feed state and the feed_provider manages the paginated list. They coordinate through Riverpod's ref, not through direct dependency.

Step 4: Pagination and Infinite Scroll

Infinite scroll is the first hard problem. The naïve implementation: a ListView that loads everything falls apart at a few hundred posts.

Here's a Riverpod AsyncNotifier that handles cursor-based pagination:

@riverpod
class FeedNotifier extends _$FeedNotifier {
  static const _pageSize = 20;
  String? _nextCursor;
  bool _isFetchingMore = false;

  @override
  Future<List<Post>> build() async {
    // Load first page + seed from cache if available
    final cached = await ref.read(feedLocalSourceProvider).getCachedPosts();
    if (cached.isNotEmpty) {
      // Show cache immediately, refresh in background
      _refreshInBackground();
      return cached;
    }
    return _fetchPage(cursor: null);
  }

  Future<void> loadMore() async {
    if (_isFetchingMore || _nextCursor == null) return;
    _isFetchingMore = true;

    final currentPosts = state.valueOrNull ?? [];
    final page = await ref
        .read(feedRepositoryProvider)
        .getFeedPage(cursor: _nextCursor, limit: _pageSize);

    _nextCursor = page.nextCursor;
    state = AsyncData([...currentPosts, ...page.posts]);
    _isFetchingMore = false;
  }

  Future<List<Post>> _fetchPage({required String? cursor}) async {
    final page = await ref
        .read(feedRepositoryProvider)
        .getFeedPage(cursor: cursor, limit: _pageSize);
    _nextCursor = page.nextCursor;
    await ref.read(feedLocalSourceProvider).cachePosts(page.posts);
    return page.posts;
  }

  void _refreshInBackground() {
    Future.microtask(() async {
      final freshPosts = await _fetchPage(cursor: null);
      state = AsyncData(freshPosts);
    });
  }

  bool get hasMore => _nextCursor != null;
}

In the screen, trigger loadMore() before the user reaches the bottom, not at the last item, but a few items before it:

NotificationListener<ScrollNotification>(
  onNotification: (notification) {
    if (notification.metrics.pixels >
        notification.metrics.maxScrollExtent - 400) {
      ref.read(feedNotifierProvider.notifier).loadMore();
    }
    return false;
  },
  child: ListView.builder(
    itemCount: posts.length + (hasMore ? 1 : 0),
    itemBuilder: (context, index) {
      if (index == posts.length) return const FeedLoadingIndicator();
      return PostCard(post: posts[index]);
    },
  ),
)

The 400-pixel threshold means the next page starts loading before the user sees the end of the list. The experience feels seamless.

Step 5: Optimistic UI for Likes and Comments

Optimistic UI is the practice of updating the local state immediately when a user takes an action, before the server confirms it, then rolling back if the server rejects it. It's what makes a like button feel instant rather than laggy.

The pattern has three steps: apply the optimistic update, fire the network request, and roll back on failure.

@riverpod
class LikeNotifier extends _$LikeNotifier {
  @override
  void build() {}

  Future<void> toggleLike(String postId) async {
    final feedNotifier = ref.read(feedNotifierProvider.notifier);
    final currentPosts = ref.read(feedNotifierProvider).valueOrNull ?? [];

    // Find the post
    final postIndex = currentPosts.indexWhere((p) => p.id == postId);
    if (postIndex == -1) return;
    final post = currentPosts[postIndex];

    // Step 1: Apply optimistic update immediately
    final optimisticPost = post.copyWith(
      isLikedByMe: !post.isLikedByMe,
      likeCount: post.isLikedByMe ? post.likeCount - 1 : post.likeCount + 1,
    );
    feedNotifier.patchPost(postIndex, optimisticPost);

    // Step 2: Fire the network request
    try {
      await ref.read(feedRepositoryProvider).toggleLike(postId);
    } catch (e) {
      // Step 3: Roll back on failure
      feedNotifier.patchPost(postIndex, post);
      // Show a snackbar or error indicator
    }
  }
}

The patchPost method on FeedNotifier replaces a single post in the list without rebuilding the whole feed. This is an important performance detail when the list has hundreds of items.

The tradeoff to name explicitly in an interview: optimistic UI can produce an inconsistent state if the server is the source of truth for like counts. Two users liking simultaneously might both see their local count increment from 41 to 42, but the real count is 43. For a social app, this is usually acceptable. You show the user their action was registered, and the next feed refresh corrects the count. For financial transactions, an optimistic UI is inappropriate. Know where to draw the line.

Step 6: Real-Time Updates

Real-time feed updates and new posts appearing while the user is looking at the screen require a persistent connection. WebSocket is the right tool here. Server-Sent Events work too, but WebSocket is bidirectional, which matters if you later want to push events (typing indicators, presence).

Design the WebSocket layer as a singleton service, not inside the feed feature:

// core/realtime/realtime_service.dart

class RealtimeService {
  WebSocketChannel? _channel;
  final _controller = StreamController<RealtimeEvent>.broadcast();

  Stream<RealtimeEvent> get events => _controller.stream;

  Future<void> connect(String token) async {
    _channel = WebSocketChannel.connect(
      Uri.parse('wss://api.yourapp.com/ws?token=$token'),
    );

    _channel!.stream.listen(
      (data) {
        final event = RealtimeEvent.fromJson(jsonDecode(data as String));
        _controller.add(event);
      },
      onError: (_) => _scheduleReconnect(),
      onDone: () => _scheduleReconnect(),
    );
  }

  void _scheduleReconnect() {
    Future.delayed(const Duration(seconds: 3), connect);
  }

  void dispose() {
    _channel?.sink.close();
    _controller.close();
  }
}

Then in the feed layer, listen to the stream and patch state when new posts arrive:

@riverpod
class RealtimeFeedNotifier extends _$RealtimeFeedNotifier {
  StreamSubscription? _subscription;

  @override
  void build() {
    _subscription = ref
        .read(realtimeServiceProvider)
        .events
        .where((e) => e.type == RealtimeEventType.newPost)
        .listen((event) {
      final newPost = Post.fromJson(event.payload);
      ref.read(feedNotifierProvider.notifier).prependPost(newPost);
    });

    ref.onDispose(() => _subscription?.cancel());
  }
}

The UX decision worth raising in an interview: do you silently prepend new posts to the top of the feed, or do you show a "3 new posts, tap to refresh" banner?

Silent prepend is jarring: the user is reading post 5, and suddenly they're reading post 8. The banner pattern (used by Twitter/X and LinkedIn) is almost always the better choice. It signals freshness without disrupting reading position.

Step 7: Offline and Error States

An offline-capable feed has two distinct requirements: show something useful when there's no connection, and queue interactions (likes, comments) so they fire when connectivity returns.

For showing cached content, the repository pattern handles this cleanly:

// feed_repository.dart

Future<List<Post>> getFeed({String? cursor}) async {
  try {
    final page = await _remoteSource.getFeedPage(cursor: cursor);
    await _localSource.cachePosts(page.posts);
    return page.posts;
  } on DioException catch (e) {
    if (e.type == DioExceptionType.connectionError) {
      // Network unavailable — return cache
      final cached = await _localSource.getCachedPosts();
      if (cached.isNotEmpty) return cached;
    }
    rethrow;
  }
}

For queuing interactions offline, keep a simple pending actions queue in local storage:

@freezed
class PendingAction with _$PendingAction {
  const factory PendingAction.like({
    required String postId,
    required bool isLike,
    required DateTime queuedAt,
  }) = PendingLike;

  const factory PendingAction.comment({
    required String postId,
    required String content,
    required DateTime queuedAt,
  }) = PendingComment;
}

When connectivity returns (detected via connectivity_plus), drain the queue and fire each action in order. If an action fails after retry, surface it to the user. Don't silently drop it.

Step 8: Performance Considerations

A feed is one of the most performance-sensitive screens in any app. There are a few non-negotiable practices:

First, use ListView.builder, never ListView with a children list. Builder renders only the items currently on screen. A children list renders all of them at once (which would be catastrophic for a feed of 200+ posts).

Second, keep PostCard build methods cheap. Every rebuild of a postcard is expensive at scale. Use const constructors everywhere possible. Avoid rebuilding the whole card when only the like count changes. Isolate the like button into its own Riverpod consumer.

// Bad — whole PostCard rebuilds when like changes
class PostCard extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final post = ref.watch(feedNotifierProvider)
        .valueOrNull
        ?.firstWhere((p) => p.id == postId);
    // ...
  }
}

// Good — only LikeButton rebuilds
class LikeButton extends ConsumerWidget {
  final String postId;
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final post = ref.watch(
      feedNotifierProvider.select(
        (state) => state.valueOrNull?.firstWhere((p) => p.id == postId),
      ),
    );
    // Only rebuilds when this specific post's like state changes
  }
}

Third, cache network images aggressively. Use cached_network_image with a memory cache limit. On a feed with avatars and post images, uncached network images are the single biggest source of jank.

And lastly, dispose WebSocket connections on screen exit. Don't keep a real-time connection alive when the user navigates away. Riverpod's ref.onDispose makes this straightforward, but it's easy to miss.

6. Other Questions to Prepare For

The social feed covers most of the hard architectural territory. These additional questions round out your preparation:

Architecture & structure:

  • How would you structure a large Flutter app for a team of 10 engineers?

  • How do you handle shared state between two features that shouldn't know about each other?

  • Walk me through how you'd design the data layer for an offline-first app.

State management:

  • Compare Riverpod, Bloc, and Redux from an architecture standpoint (not just API differences).

  • How do you prevent the state from leaking between sessions after a user logs out?

Networking & data:

  • How would you handle token refresh across concurrent requests?

  • Walk me through optimistic UI for a financial transaction. How is it different from liking a post?

Performance:

  • A screen has 10,000 items. How do you render it without jank?

  • How do you design an image-loading system for a feed with mixed media types?

Multi-platform:

  • How would you share models and business logic between a Flutter mobile app and a Dart backend?

  • What changes about your architecture when you add a web as a target?

For each of these, use the same framework: clarify the constraints, define the data model, name the layers, solve the hard problems explicitly, and address failure states.

7. Key Takeaways

Systems design is not a backend discipline that Flutter engineers are exempt from. It's a way of thinking about software that becomes unavoidable as apps grow in complexity, teams grow in size, and AI agents become part of the development workflow.

The social feed scenario illustrates five principles that apply across every frontend systems design problem:

1. Layer Boundaries Are Load-bearing

The repository pattern, the separation of real-time from data fetching, and the isolation of pending actions aren't academic choices. They're what makes the system testable, navigable, and maintainable when requirements change.

2. The Data Model Anchors Everything

Decisions you make in the model (like cursor-based pagination, isLikedByMe on the post, and integer counts instead of arrays) ripple through every layer. Get the model right before designing anything else.

3. Optimistic UI is a UX Contract, Not Just a Pattern

When you apply an optimistic update, you're making a promise to the user. Know when that promise is appropriate (social interactions) and when it isn't (financial transactions).

4. Real-time is an Architecture Concern, Not a Feature

A WebSocket connection is a persistent resource that needs to be managed, connected when needed, disconnected when not, and reconnected on failure. Design it as infrastructure, not as part of a single screen.

5. Offline is a First-class State

Not an edge case, not a "nice to have." In markets with unreliable connectivity, which includes most of the world's fastest-growing mobile markets, an app that shows nothing when the network drops is a broken app.

The engineers who understand these principles and can articulate them out loud under interview pressure are the ones who get hired to build the systems that millions of people use.

]]> <![CDATA[ A Deep Dive into Behavioral Patterns: The Visitor Design Pattern and its Clean Operations Across Complex Object Structures ]]> https://www.freecodecamp.org/news/the-visitor-design-pattern-and-its-clean-operations-across-complex-object-structures/ 6a74b21fcf90c22a668963b6 Thu, 06 Aug 2026 16:11:11 +0000 There's a problem that shows up in almost every growing software system, and most developers don't even realize they're hitting it until the damage is already done.

You have a set of objects: different types, shapes, and data. And at some point, someone asks you to perform an operation on all of them, like exporting them them to PDF, sending them a notification, generating a report, or calculating their fees.

Your first instinct might be to write a function that checks the type and branches accordingly, like an if-else block or switch statement. Something that says: if this is a NewUser, do this. If this is a JointAccountUser, do that. It works, you ship it, and everyone is happy.

Then another operation comes in. And another. Every single time, you go back to the same place and add another branch. The function grows. The class grows. The test surface grows. What started as a clean model is now a god object that knows how to do everything for everyone.

The Visitor Design Pattern exists to break this cycle completely.

Table of Contents

What is the Visitor Design Pattern?

The Visitor pattern is a behavioral design pattern that lets you define a new operation on a family of objects without changing the objects themselves.

The key word there is behavioral. Behavioral patterns are about how objects communicate and distribute responsibility. Where creational patterns deal with how objects are created and structural patterns deal with how they are composed, behavioral patterns deal with how they interact and who is responsible for what.

The Visitor pattern specifically deals with the question of who should own an operation when that operation needs to work differently across multiple object types.

The classic answer is: put the operation on each object. Give each class a method that handles the operation for its own type. But this breaks down the moment you have multiple operations, because now every new operation means touching every class. You're spreading one concern across your entire object hierarchy.

The Visitor pattern flips this. Instead of spreading the operation across the objects, you collect it into one place called a Visitor. The objects simply accept the visitor and let it do its work. Adding a new operation means creating a new Visitor. The existing objects don't change at all.

This is the Open/Closed Principle working exactly as intended: open for extension, closed for modification.

The Problem the Visitor Pattern Solves

Let me show you exactly what this looks like without the Visitor pattern.

Say you have a fintech platform with four types of users: existing customers, new customers, minor account holders, and joint account holders. Your product manager comes in and asks you to add document export. Every user type should be exportable to PDF, Excel, and CSV.

Without Visitor, the natural approach looks something like this:

class ExistingUser {
  final int id;
  final String firstName;
  final String lastName;
  final DateTime lastPaymentDate;
  final num accountBalance;

  String exportToPdf() {
    return '$firstName\n$lastName\n$lastPaymentDate\n$accountBalance';
  }

  String exportToExcel() {
    return '$firstName,$lastName,$lastPaymentDate,$accountBalance';
  }

  String exportToCsv() {
    return '"$firstName","$lastName","$lastPaymentDate","$accountBalance"';
  }
}

And you repeat this for NewUser, MinorAccountUser, and JointAccountUser. Twelve methods spread across four classes just for document export.

Now the product manager comes back. They want notifications: email, SMS, and Push. Back you go to all four classes, adding three more methods each. Twelve more methods spread across the same four classes.

Then they want fee calculation. Then they want KYC status checks. Every new operation multiplies across every user type. The classes grow, the reasons to change multiply, and testing becomes painful.

This is the exact problem the Visitor pattern was built to solve.

Core Components

The Visitor pattern has four core components. Understanding each one before looking at code makes the implementation much easier to follow.

The Visitor Interface

This is the contract that every visitor must implement. It declares one method per object type it needs to visit. A visitor that handles four user types declares four visit methods, one for each type.

The Concrete Visitors

These are the real implementations of the Visitor interface. Each one represents a single operation and knows how to handle every object type. A PdfHandler is a concrete visitor. An ExcelHandler is a concrete visitor. A SmsNotificationHandler is a concrete visitor. Each one has one job and knows how to do that job for every user type.

The Consumer Interface (also called Element or Acceptor)

This is the contract that every object in the hierarchy must implement. It declares a single accept method that takes a Visitor and calls the right visit method on it. This is the double dispatch mechanism that makes the pattern work.

The Concrete Consumers

These are the real objects in the hierarchy: ExistingCustomers, NewCustomers, MinorCustomer, and JointCustomer. Each one implements accept by calling the specific visit method that corresponds to its own type.

Think of it this way. The Visitor interface is implemented by every operation you want to perform: PdfHandler, ExcelHandler, and CsvHandler. Each of these knows how to handle all four user types.

The Consumer interface is implemented by every object in the hierarchy: ExistingCustomers, NewCustomers, MinorCustomer, and JointCustomer. Each of these knows how to receive a visitor and route it to the correct method.

When you call existingCustomer.accept(pdfHandler), ExistingCustomers calls pdfHandler.visitExistingCustomer(this) and passes itself as the argument. The right method fires automatically. There's no type checking, if-else, or switch. The object tells the visitor who it is, and the visitor knows exactly what to do with that information.

Real World Example One: Document Export

This is a real scenario from a fintech platform. There are four user types with different data structures, all needing to export their information to three document formats: PDF, Excel, and CSV.

Step 1: Define the User Models

class ExistingUser {
  final int id;
  final String firstName;
  final String lastName;
  final DateTime lastPaymentDate;
  final num accountBalance;

  const ExistingUser({
    required this.id,
    required this.firstName,
    required this.lastName,
    required this.lastPaymentDate,
    required this.accountBalance,
  });
}

class NewUser {
  final String firstName;
  final String lastName;

  const NewUser({
    required this.firstName,
    required this.lastName,
  });
}

class MinorAccountUser {
  final int age;
  final int guardianId;
  final String firstName;
  final String lastName;
  final String guardianName;

  const MinorAccountUser({
    required this.age,
    required this.guardianId,
    required this.firstName,
    required this.lastName,
    required this.guardianName,
  });
}

class JointAccountUser {
  final int jointAccountId;
  final List<String> accountHoldersInfo;
  final num accountBalance;

  const JointAccountUser({
    required this.jointAccountId,
    required this.accountHoldersInfo,
    required this.accountBalance,
  });
}

We have four models. Each one owns its own data and nothing else. There's no export logic or notification logic. And no business operations of any kind. Just clean data structures.

This is exactly how it should be. The model's job is to hold data. The visitor's job is to operate on it.

Step 2: Define the Visitor and Consumer Interfaces

abstract class UserVisitor<T> {
  T visitExistingCustomer(ExistingUser user);
  T visitNewCustomer(NewUser user);
  T visitMinorCustomer(MinorAccountUser user);
  T visitJointCustomer(JointAccountUser user);
}

abstract class UserConsumer {
  T accept<T>(UserVisitor<T> visitor);
}

UserVisitor<T> is generic. The type parameter T represents what the visitor returns. A document export visitor returns a String. A fee calculation visitor might return a double. A validation visitor might return a bool. The same pattern works for any return type.

UserConsumer declares the accept method. Every object in the hierarchy must implement this. The accept method is what makes the double dispatch work. The object receives the visitor and immediately calls the right visit method on it, passing itself as the argument.

Step 3: Implement the Concrete Consumers

class ExistingCustomers implements UserConsumer {
  final ExistingUser user;
  ExistingCustomers({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitExistingCustomer(user);
  }
}

class NewCustomers implements UserConsumer {
  final NewUser user;
  NewCustomers({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitNewCustomer(user);
  }
}

class MinorCustomer implements UserConsumer {
  final MinorAccountUser user;
  MinorCustomer({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitMinorCustomer(user);
  }
}

class JointCustomer implements UserConsumer {
  final JointAccountUser user;
  JointCustomer({required this.user});

  @override
  T accept<T>(UserVisitor<T> visitor) {
    return visitor.visitJointCustomer(user);
  }
}

Each consumer wraps one user model and implements accept by forwarding to the correct visit method. This is the entire job of a concrete consumer. It knows who it is, and it tells the visitor by calling the right method.

Notice that none of these classes know anything about PDF, Excel, CSV, email, SMS, or any operation. They're completely decoupled from every operation that will ever be performed on them.

Step 4: Implement the Concrete Visitors

class PdfHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '${user.firstName} ${user.lastName}'
        '\nBalance: ${user.accountBalance}'
        '\nLast Payment: ${user.lastPaymentDate}';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '${user.firstName} ${user.lastName}';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '${user.firstName} ${user.lastName}'
        '\nAge: ${user.age}'
        '\nGuardian: ${user.guardianName} (ID: ${user.guardianId})';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.join(', ');
    return 'Joint Account ID: ${user.jointAccountId}'
        '\nHolders: $holders'
        '\nBalance: ${user.accountBalance}';
  }
}

class ExcelHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '${user.firstName}\t${user.lastName}'
        '\t${user.accountBalance}\t${user.lastPaymentDate}';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '${user.firstName}\t${user.lastName}';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '${user.firstName}\t${user.lastName}'
        '\t${user.age}\t${user.guardianName}\t${user.guardianId}';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.join('\t');
    return '${user.jointAccountId}\t$holders\t${user.accountBalance}';
  }
}

class CsvHandler implements UserVisitor<String> {
  @override
  String visitExistingCustomer(ExistingUser user) {
    return '"${user.firstName}","${user.lastName}"'
        ',"${user.accountBalance}","${user.lastPaymentDate}"';
  }

  @override
  String visitNewCustomer(NewUser user) {
    return '"${user.firstName}","${user.lastName}"';
  }

  @override
  String visitMinorCustomer(MinorAccountUser user) {
    return '"${user.firstName}","${user.lastName}"'
        ',"${user.age}","${user.guardianName}","${user.guardianId}"';
  }

  @override
  String visitJointCustomer(JointAccountUser user) {
    final holders = user.accountHoldersInfo.map((h) => '"$h"').join(',');
    return '"${user.jointAccountId}",$holders,"${user.accountBalance}"';
  }
}

Each handler implements the visitor interface and knows exactly how to format each user type for its specific document format. PdfHandler uses newlines and labels. ExcelHandler uses tabs. CsvHandler wraps values in quotes and separates with commas.

The formatting logic for each document type lives in exactly one class. If the PDF format changes, you touch only PdfHandler. If the CSV format changes, you touch only CsvHandler. The user models never change.

Step 5: Use It

void existingUserLogic() {
  final customer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  final pdf = customer.accept(PdfHandler());
  final excel = customer.accept(ExcelHandler());
  final csv = customer.accept(CsvHandler());

  print('PDF:\n$pdf\n');
  print('Excel:\n$excel\n');
  print('CSV:\n$csv\n');
}

void newUserLogic() {
  final customer = NewCustomers(
    user: NewUser(
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

void minorUserLogic() {
  final customer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      guardianName: 'Inioluwa',
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

void jointUserLogic() {
  final customer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  customer.accept(PdfHandler());
  customer.accept(ExcelHandler());
  customer.accept(CsvHandler());
}

The same customer object accepts any visitor with the same call. The type dispatch happens automatically through the accept method. There's no type checking anywhere in the calling code, and no if-else or switch. Just customer.accept(handler) and the right method fires.

Now think about what happens when you need to add an XML export. You create one new class, XmlHandler, implement the four visit methods, and that's it. You don't touch ExistingUser, NewUser, MinorAccountUser, JointAccountUser, or any of the existing handlers. The system is genuinely open for extension and closed for modification.

Real World Example Two: Notification System

Here we have the same four user types and the same pattern. But it's a different operation entirely.

Your platform needs to notify users about account events. But not every user type should be notified the same way.

Existing users get email and push notifications. New users only get email because they haven't fully set up their profile yet. Minor account users get SMS to their guardian's number. Joint account users get notified on all channels because multiple people share the account.

Without the Visitor pattern, this logic would spread across all four user models or collapse into one enormous function full of type checks. With Visitor, it lives in three focused classes.

The Notification Visitor Interface

abstract class NotificationVisitor {
  void visitExistingCustomer(ExistingUser user);
  void visitNewCustomer(NewUser user);
  void visitMinorCustomer(MinorAccountUser user);
  void visitJointCustomer(JointAccountUser user);
}

This visitor returns void because notifications are side effects. They send messages, they don't return values.

The Concrete Notification Visitors

class EmailNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Sending email to existing customer: ${user.firstName}');
    // email service call with full account details
  }

  @override
  void visitNewCustomer(NewUser user) {
    print('Sending welcome email to new customer: ${user.firstName}');
    // welcome email with onboarding steps
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    print('Sending email to guardian: ${user.guardianName}');
    // email goes to guardian, not the minor
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Sending email to joint holder: $holder');
      // all account holders get notified
    }
  }
}

class SmsNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Sending SMS to existing customer: ${user.firstName}');
  }

  @override
  void visitNewCustomer(NewUser user) {
    // new users are not SMS-verified yet, skip
    print('New customer ${user.firstName} not SMS-eligible yet');
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    print('Sending SMS to guardian ${user.guardianName} for minor ${user.firstName}');
    // SMS goes to guardian's registered number
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Sending SMS to joint holder: $holder');
    }
  }
}

class PushNotificationHandler implements NotificationVisitor {
  @override
  void visitExistingCustomer(ExistingUser user) {
    print('Push notification to existing customer: ${user.firstName}');
  }

  @override
  void visitNewCustomer(NewUser user) {
    print('Push notification to new customer: ${user.firstName}');
  }

  @override
  void visitMinorCustomer(MinorAccountUser user) {
    // minors do not have the app installed yet, guardian gets push
    print('Push notification to guardian: ${user.guardianName}');
  }

  @override
  void visitJointCustomer(JointAccountUser user) {
    for (final holder in user.accountHoldersInfo) {
      print('Push notification to joint holder: $holder');
    }
  }
}

Each handler knows the specific rules for each user type. SmsNotificationHandler knows that new users aren't SMS-verified yet. PushNotificationHandler knows that minor account notifications go to the guardian. EmailNotificationHandler knows that joint account holders all need to be notified individually.

This business logic lives in exactly one place per notification channel. When the rules change (and they always change), you update one class.

Using the Notification Visitors

void notifyExistingUser() {
  final customer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

void notifyMinorUser() {
  final customer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      guardianName: 'Inioluwa',
    ),
  );

  // all three channels fire, each with minor-specific rules
  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

void notifyJointUser() {
  final customer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  customer.accept(EmailNotificationHandler());
  customer.accept(SmsNotificationHandler());
  customer.accept(PushNotificationHandler());
}

The calling code is identical regardless of the user type or the notification channel. The dispatch is automatic. The rules live inside the visitors.

When WhatsApp notifications become a requirement (and they will), you create one WhatsAppNotificationHandler class with four visit methods. Nothing else changes.

Real World Example Three: Fee Calculation

Again, we have the same four user types and the same pattern. And once again, we have a completely different operation.

Your platform needs to calculate monthly maintenance fees. But each user type has different rules.

Existing customers pay a flat monthly fee based on their account balance. New customers are fee-exempt for their first three months. Minor account holders pay a reduced fee because their accounts have restricted features. Joint account holders have their fee split equally across all account holders.

Without Visitor, this logic ends up as a giant method somewhere with four branches, or worse, it leaks into the user models themselves. With Visitor, it lives in one focused class.

The Fee Visitor Interface

abstract class FeeVisitor {
  double visitExistingCustomer(ExistingUser user);
  double visitNewCustomer(NewUser user);
  double visitMinorCustomer(MinorAccountUser user);
  double visitJointCustomer(JointAccountUser user);
}

This visitor returns a double because fee calculation produces a numeric value.

The Concrete Fee Visitor

class MonthlyFeeCalculator implements FeeVisitor {
  @override
  double visitExistingCustomer(ExistingUser user) {
    // 0.5% of account balance, minimum 500, maximum 5000
    final fee = user.accountBalance * 0.005;
    return fee.clamp(500, 5000).toDouble();
  }

  @override
  double visitNewCustomer(NewUser user) {
    // new customers are fee-exempt for the first 3 months
    return 0.0;
  }

  @override
  double visitMinorCustomer(MinorAccountUser user) {
    // flat reduced fee for minor accounts
    return 150.0;
  }

  @override
  double visitJointCustomer(JointAccountUser user) {
    // standard fee split equally across all holders
    const standardFee = 2000.0;
    return standardFee / user.accountHoldersInfo.length;
  }
}

Every fee rule for every user type lives in this one class. When the fee structure changes for existing customers, you touch one method in one class. When minor account fees are updated, same thing. None of the user models change, and no other visitor changes.

Using the Fee Visitor

void calculateFees() {
  final existingCustomer = ExistingCustomers(
    user: ExistingUser(
      id: 10,
      firstName: 'Oluwaseyi',
      lastName: 'Fatunmole',
      lastPaymentDate: DateTime.now(),
      accountBalance: 7373773.39,
    ),
  );

  final newCustomer = NewCustomers(
    user: NewUser(
      firstName: 'Aderonke',
      lastName: 'Fatunmole',
    ),
  );

  final minorCustomer = MinorCustomer(
    user: MinorAccountUser(
      age: 15,
      guardianId: 82882,
      firstName: 'Inioluwa',
      lastName: 'Fatunmole',
      guardianName: 'Oluwaseyi',
    ),
  );

  final jointCustomer = JointCustomer(
    user: JointAccountUser(
      jointAccountId: 92,
      accountHoldersInfo: [
        'Oluwaseyi',
        'Aderonke',
        'Inioluwa',
        'Tiwaloluwa',
      ],
      accountBalance: 9200020202.22,
    ),
  );

  final calculator = MonthlyFeeCalculator();

  final existingFee = existingCustomer.accept(calculator);
  final newFee = newCustomer.accept(calculator);
  final minorFee = minorCustomer.accept(calculator);
  final jointFee = jointCustomer.accept(calculator);

  print('Existing customer fee: NGN $existingFee');
  print('New customer fee: NGN $newFee');
  print('Minor account fee: NGN $minorFee');
  print('Joint account fee per holder: NGN $jointFee');
}

The output:

Existing customer fee: NGN 5000.0
New customer fee: NGN 0.0
Minor account fee: NGN 150.0
Joint account fee per holder: NGN 500.0

When a PremiumFeeCalculator is needed for a new tier of customers, you create one new class that implements FeeVisitor. The user models stay exactly as they are. The MonthlyFeeCalculator stays exactly as it is. The accept methods on all four consumers stay exactly as they are.

The Power of Combining All Three Operations

Here's what makes the Visitor pattern truly shine in a system like this. You have the same four user types, and you can run any combination of visitors on any of them in the same call chain.

void processUser(UserConsumer customer) {
  final pdf = customer.accept(PdfHandler());
  final csv = customer.accept(CsvHandler());

  customer.accept(EmailNotificationHandler());
  customer.accept(PushNotificationHandler());

  final fee = customer.accept(MonthlyFeeCalculator());

  print('Fee: NGN $fee');
  print('Documents generated and notifications sent');
}

One function, any user type, any combination of operations. The consumer doesn't care which visitors it receives. The visitors don't care which consumers call them. They speak to each other through the interface, and the interface guarantees everything works correctly.

We have three completely different operations (document export, notifications, and fee calculation) all applied to the same object with the same call pattern. None of these operations know about each other. None of them touch the user models. Each one lives in its own focused class with its own single reason to change.

When to Use the Visitor Pattern

Use Visitor when you have a stable set of object types and a growing set of operations on them.

The pattern shines when the object hierarchy is unlikely to change frequently. It's optimized for adding new operations, not new types. Adding a new user type means updating every existing visitor. If your object types change constantly, Visitor creates more work than it saves.

It's also very effective when you need to perform multiple unrelated operations on a family of objects without polluting their classes with that logic. Document export, notification handling, fee calculation, and KYC validation are all unrelated operations. Each belongs in its own visitor, not scattered across the user models.

Visitor also works well when you want clean separation between data and behavior. The models hold data and the visitors define behavior. This makes both easier to understand, easier to test, and easier to maintain independently.

When Not to Use It

Avoid Visitor when the object hierarchy changes frequently. Every time you add a new type, you must update every existing visitor. In a system where new user types appear regularly, this becomes painful quickly.

It's also not helpful when you only have one or two operations. For simple cases, the overhead of creating visitor interfaces, consumer interfaces, and multiple classes is not worth the benefit.

And avoid it when the operations are tightly coupled to the object's internal state in ways that make sense to keep together. Some behavior naturally belongs on the object itself.

Conclusion

The Visitor Design Pattern solves a problem that most developers only recognize after they've already made a mess of it. You have a family of objects with different types and different data. Operations come in one after another. Without a deliberate structure, those operations spread everywhere: into the models, utility classes, and massive switch statements that nobody wants to touch.

Visitor collects each operation into one focused class. The models stay clean and the operations stay isolated. Adding a new operation means creating one new class. The existing code doesn't change.

In the fintech examples above, we have three entirely different concerns: document export, notifications, and fee calculation. All are handled by handled by focused classes, none of which know anything about each other. The user models don't know about PDF or email or fees. The PdfHandler doesn't know about SMS. The MonthlyFeeCalculator doesn't know about push notifications. Each class has exactly one reason to exist and exactly one reason to change.

That s what a well-applied Visitor pattern looks like in practice. Clean, focused, and genuinely extensible.

Happy coding!

]]> <![CDATA[ How to Structure Large Flutter Applications for Scalable and Maintainable Growth ]]> https://www.freecodecamp.org/news/how-to-structure-large-flutter-applications-for-scalable-and-maintainable-growth/ 6a3ab6b8b961d002e47ff767 Tue, 23 Jun 2026 16:39:20 +0000 Flutter makes it extremely fast to build UIs. That speed is one of the framework’s greatest strengths, but it also creates a subtle problem: applications often grow much faster than their architecture.

A few screens quickly become dozens. Features that initially felt isolated start interacting with each other. Authentication affects navigation. Notifications affect onboarding. Feature flags alter business flows. Local persistence introduces synchronization concerns. State begins leaking between unrelated parts of the application.

None of this happens suddenly.

Most Flutter codebases degrade progressively. Small shortcuts that felt harmless early on accumulate until changing one feature requires understanding half the application.

This is usually where teams begin introducing architecture patterns reactively. Unfortunately, many applications attempt to solve scaling problems by adding abstraction layers without first understanding where the actual complexity comes from.

Large applications rarely fail because they lack patterns. They fail because ownership boundaries become unclear.

This article presents a practical approach to structuring large Flutter applications so complexity remains visible and manageable as the codebase evolves. The focus here isn't theoretical purity. It's long-term maintainability under real production constraints.

Table of Contents

Prerequisites

This guide assumes familiarity with Flutter widgets, asynchronous programming with Future and async/await, and basic state management approaches such as Provider, Riverpod, or BLoC.

You should also already feel comfortable building applications beyond simple demos. The article focuses less on Flutter fundamentals and more on architectural decisions that emerge once applications become long-lived systems maintained by multiple developers over time.

What Makes Flutter Apps Hard to Scale

Large applications are rarely difficult because of UI complexity alone. Most scaling problems emerge from coordination complexity.

A simple login flow illustrates this well. Initially, authentication may only involve sending credentials, receiving a token, and navigating to a home screen.

But production systems evolve quickly. Authentication eventually becomes responsible for:

  • restoring sessions

  • refreshing expired tokens

  • preloading user data

  • triggering analytics

  • handling onboarding state

  • synchronizing local caches

  • applying feature flags

  • supporting deep links

The UI may still appear simple while the underlying coordination logic becomes increasingly interconnected.

Without architectural boundaries, this complexity spreads everywhere:

  • widgets

  • repositories

  • route guards

  • interceptors

  • global services

  • state containers

At that point, even small changes become risky because unrelated systems begin sharing lifecycle assumptions.

This is one of the most important architectural realities in Flutter applications: complexity scales through interactions, not screens.

Why Small Architectures Break Down

Many Flutter applications begin with a structure like this:

lib/
  screens/
  widgets/
  services/
  providers/
  models/

For small applications, this works perfectly well. The problem appears once features become larger and more interconnected.

Imagine implementing a “favorites” feature. The screen lives in screens/. State management lives in providers/. Networking logic lives in services/. Models live in models/.

A single business capability now spans the entire project structure.

This introduces a subtle but important problem: the application structure no longer reflects the product structure.

Developers stop thinking in terms of features and start thinking in terms of technical categories.

Over time, ownership becomes ambiguous, dependencies become implicit, unrelated features become coupled, and debugging requires jumping constantly across folders.

The architecture begins optimizing for file classification instead of system comprehension.

That distinction matters more than it initially appears.

Large systems survive through clarity of ownership. Once ownership boundaries become blurry, maintenance costs rise aggressively.

Organizing by Feature

The most effective way to reduce architectural fragmentation is organizing the application around business capabilities instead of technical layers.

A feature should own everything required for its behavior:

  • presentation

  • business logic

  • state

  • persistence

  • tests

For example:

lib/
  features/
    authentication/
      presentation/
      domain/
      data/

As the feature evolves, its structure can grow naturally:

features/
  authentication/
    presentation/
      pages/
      widgets/
      state/
    domain/
      entities/
      usecases/
      repositories/
    data/
      models/
      repositories/
      sources/

Now the authentication system exists as a coherent unit instead of being scattered across the codebase.

This dramatically improves locality of change.

When developers modify authentication behavior, they immediately know where state lives, where business rules are defined, how persistence is implemented, and where tests belong.

This becomes increasingly important as multiple developers work simultaneously on unrelated features. Clear ownership boundaries reduce accidental coupling and make parallel development significantly safer.

The presentation layer reacts to state changes:

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

  @override
  Widget build(BuildContext context) {
    return BlocConsumer<LoginCubit, LoginState>(
      listener: (context, state) {
        if (state.isSuccess) {
          context.go('/home');
        }
      },
      builder: (context, state) {
        return LoginView(
          isLoading: state.isLoading,
          onSubmit: (email, password) {
            context.read<LoginCubit>().login(
              email,
              password,
            );
          },
        );
      },
    );
  }
}

The important detail here is not BLoC itself. It's the separation of responsibilities.

The widget renders UI and forwards user intent. It doesn't coordinate infrastructure concerns directly.

That orchestration happens elsewhere:

class LoginCubit extends Cubit<LoginState> {
  final LoginUseCase loginUseCase;

  LoginCubit(this.loginUseCase)
      : super(const LoginState.initial());

  Future<void> login(
    String email,
    String password,
  ) async {
    emit(state.loading());

    final result = await loginUseCase(
      email,
      password,
    );

    result.fold(
      (failure) => emit(
        state.failure(failure.message),
      ),
      (_) => emit(
        state.success(),
      ),
    );
  }
}

This distinction prevents UI code from slowly becoming an orchestration layer filled with side effects.

Separating Presentation, Domain, and Data

One of the most important architectural boundaries in large Flutter applications is separating presentation, business logic, and infrastructure concerns.

These layers evolve at different speeds: the UI changes constantly, while business rules evolve more slowly and infrastructure changes unpredictably.

Without separation, infrastructure concerns gradually leak upward into presentation code until widgets become tightly coupled to APIs, databases, caching, retries, and persistence logic.

A common anti-pattern looks like this:

ElevatedButton(
  onPressed: () async {
    final response = await dio.post(
      '/login',
      data: {
        'email': email,
        'password': password,
      },
    );

    if (response.statusCode == 200) {
      Navigator.pushNamed(
        context,
        '/home',
      );
    }
  },
)

This may seem harmless initially, but it tightly couples networking, navigation, side effects, and widget lifecycle management.

The widget now owns infrastructure coordination. That becomes increasingly difficult to maintain as flows grow more complex.

Instead, the widget should simply emit user intent:

ElevatedButton(
  onPressed: () {
    context.read<LoginCubit>().login(
      email,
      password,
    );
  },
)

The orchestration belongs in the application layer.

The domain layer contains business rules and repository contracts:

abstract class AuthenticationRepository {
  Future<User> login(
    String email,
    String password,
  );
}

Use cases coordinate business behavior independently from infrastructure details:

class LoginUseCase {
  final AuthenticationRepository repository;

  LoginUseCase(this.repository);

  Future<User> call(
    String email,
    String password,
  ) {
    return repository.login(
      email,
      password,
    );
  }
}

This separation matters because business rules shouldn't depend directly on HTTP clients, databases, or serialization details.

Infrastructure belongs in the data layer:

class AuthenticationApi {
  final Dio dio;

  AuthenticationApi(this.dio);

  Future<UserDto> login(
    String email,
    String password,
  ) async {
    final response = await dio.post(
      '/login',
      data: {
        'email': email,
        'password': password,
      },
    );

    return UserDto.fromJson(
      response.data,
    );
  }
}

Repository implementations coordinate infrastructure concerns while keeping those details isolated from the rest of the system:

class AuthenticationRepositoryImpl
    implements AuthenticationRepository {
  final AuthenticationApi api;

  AuthenticationRepositoryImpl(this.api);

  @override
  Future<User> login(
    String email,
    String password,
  ) async {
    final dto = await api.login(
      email,
      password,
    );

    return dto.toDomain();
  }
}

This architecture introduces more structure, but it also creates clearer ownership boundaries and safer system evolution over time. Furthermore the implementation details are encapsulated behind the interface. This practice facilitates testing and dependency injection.

State Boundaries and State Management

Most Flutter state management discussions focus heavily on libraries.

In practice, scaling problems usually come from ownership boundaries rather than tooling.

The hardest questions are rarely should we use Riverpod? Or should we use BLoC?

The harder questions are who owns this state and how long should it live? Who can mutate it? What systems depend on it? And what rebuild boundaries exist?

Many applications eventually accumulate giant global state containers:

class AppBloc extends Bloc<AppEvent, AppState> {
  // authentication
  // profile
  // notifications
  // settings
  // analytics
}

Initially, this feels convenient because everything becomes accessible globally.

Over time, unrelated concerns begin sharing lifecycle assumptions. Features become tightly coupled through shared state. Rebuild propagation becomes harder to reason about. Debugging state transitions becomes increasingly expensive.

Instead, prefer feature-level ownership:

features/
  profile/
    state/
  checkout/
    state/
  notifications/
    state/

Each feature owns its own lifecycle and transitions.

For example:

class CartCubit extends Cubit<CartState> {
  CartCubit()
      : super(
          const CartState.empty(),
        );

  void addProduct(Product product) {
    emit(
      state.copyWith(
        products: [
          ...state.products,
          product,
        ],
      ),
    );
  }
}

This dramatically reduces hidden coupling.

Other features should interact through events, abstractions, or use cases – not direct mutation.

Global state should remain limited to concerns that are truly global and span across multiple features. For example:

  • authentication

  • localization

  • theme

  • application session

Everything else should stay scoped whenever possible.

Navigation at Scale

Navigation complexity grows much faster than most teams expect.

Initially, routing may feel trivial: push a screen, pop a screen, maybe protect a route.

But production applications introduce:

  • onboarding flows

  • deep links

  • nested navigation

  • authentication guards

  • modal coordination

  • state restoration

  • multiple navigation entry points

Navigation logic should remain isolated from business logic since this is really critical as the application grows and the developers need to focus on business logic. Decoupling navigation logic from the business one is a foundational architectural best practice.

Repositories should never know about routing:

class AuthenticationRepository {
  Future<void> login() async {
    Navigator.pushNamed(
      context,
      '/home',
    );
  }
}

This code creates coupling between infrastructure and presentation concerns.

Instead, business logic should emit outcomes:

sealed class LoginResult {}

class LoginSuccess extends LoginResult {}

class LoginFailure extends LoginResult {
  final String message;

  LoginFailure(this.message);
}

The presentation layer reacts to those outcomes:

BlocListener<LoginCubit, LoginState>(
  listener: (context, state) {
    if (state.isSuccess) {
      context.go('/home');
    }
  },
  child: const LoginView(),
)

This keeps routing decisions inside the presentation layer where they belong.

It also simplifies testing, debugging, and navigation ownership.

Managing Shared Code

Large applications inevitably accumulate shared code.

The danger is allowing folders like shared/, common/, or core/ to become dumping grounds for unrelated logic.

Shared UI primitives are excellent reuse candidates:

shared/
  widgets/
    app_button.dart
    app_text_field.dart
  theme/
  spacing/

But feature-specific logic should remain inside feature boundaries.

This quickly becomes dangerous:

shared/
  auth_helpers.dart
  checkout_utils.dart

Once business logic enters shared layers, a few things happen:

  • ownership becomes unclear

  • unrelated features become coupled

  • architectural boundaries begin dissolving

Premature abstraction often creates more long-term maintenance cost than small duplication.

If two features may evolve differently later, duplication may actually preserve isolation more effectively than forced reuse.

Maintainability matters more than maximizing reuse percentages.

Scaling Dependency Injection

Dependency injection helps isolate infrastructure and improve testability, but uncontrolled DI can easily become hidden global state.

Constructor injection remains one of the clearest approaches:

class ProfileCubit extends Cubit<ProfileState> {
  final LoadProfileUseCase loadProfile;

  ProfileCubit(this.loadProfile)
      : super(
          const ProfileState.initial(),
        );
}

Dependencies remain visible and explicit.

Feature-level registration also improves modularity:

void registerAuthenticationModule() {
  getIt.registerLazySingleton<
      AuthenticationRepository>(
    () => AuthenticationRepositoryImpl(
      getIt(),
    ),
  );

  getIt.registerFactory(
    () => LoginCubit(
      getIt(),
    ),
  );
}

Avoid arbitrary service locator access deep inside widgets:

getIt<ApiClient>()

Hidden dependencies make debugging significantly harder because ownership becomes invisible.

Dependency ownership should follow feature ownership whenever possible.

Production Considerations

Many architecture discussions stop before operational concerns appear.

Production systems introduce constraints that heavily influence architectural decisions, like:

  • startup performance

  • observability

  • rollout safety

  • migration complexity

  • debugging visibility

  • operational consistency

Avoid heavy synchronous initialization inside main():

Future<void> main() async {
  WidgetsFlutterBinding
      .ensureInitialized();

  await configureDependencies();

  runApp(
    const App(),
  );
}

Lazy initialization improves startup performance and reduces blocking work during application launch.

Observability also becomes essential once applications scale:

FlutterError.onError =
    FirebaseCrashlytics.instance
        .recordFlutterFatalError;

Without observability, debugging production issues becomes increasingly expensive because failures become difficult to reproduce locally.

Feature flags reduce deployment risk and support gradual rollouts:

if (
  featureFlags.isEnabled(
    'new_checkout',
  )
) {
  return const NewCheckoutPage();
}

return const LegacyCheckoutPage();

As teams grow, operational consistency matters more and more.

Large applications require linting, formatting, automated tests, static analysis, and pull request validation.

Architecture alone can't preserve maintainability without engineering discipline surrounding the system itself.

Conclusion

Large Flutter applications succeed when teams optimize for locality of change, explicit ownership, isolated state boundaries, predictable data flow, and maintainable system evolution.

Good architecture doesn't eliminate complexity. It makes complexity understandable.

Organize around features, keep infrastructure isolated, avoid hidden dependencies, treat state ownership seriously, and be careful with shared abstractions.

Most importantly, evolve architecture incrementally.

The best architectures are rarely designed all at once. They emerge from continuously reducing friction as the application, team, and operational complexity evolve together.

]]> <![CDATA[ Pure Headless vs. Hybrid Headless CMS: Choosing the Right Architecture for Enterprise Content Management ]]> https://www.freecodecamp.org/news/pure-headless-vs-hybrid-headless-cms-for-enterprise-content-management/ 6a35795fac5ab8c96cba139b Fri, 19 Jun 2026 17:16:15 +0000 Enterprise organisations are under constant pressure to deliver content across websites, mobile applications, customer portals, digital kiosks, smart devices, and emerging digital channels.

Customers expect consistent experiences wherever they interact with a brand, while internal teams need tools that simplify publishing, governance, localisation, and content operations.

As a result, many organisations are reevaluating their content management systems and moving away from traditional monolithic platforms. The rise of headless content management systems has introduced new possibilities for flexibility, scalability, and omnichannel content delivery.

But choosing between a Pure Headless CMS and a Hybrid Headless CMS isn't always straightforward. Both architectures support modern digital experiences, but they differ significantly in how they manage content, presentation layers, workflows, and enterprise requirements.

In this article, we'll explore the differences between Pure Headless CMS and Hybrid Headless CMS architectures, examine their strengths and limitations, and help enterprise decision-makers determine which approach best supports their long-term Enterprise Content Management strategy.

What We'll Cover:

Understanding Headless CMS Architecture

A traditional CMS like WordPress and Ghost combines content management and content presentation within a single system. The backend stores content, while the frontend controls how that content is displayed.

A headless CMS like Strapi and Contentful removes the presentation layer entirely. Content is managed in the backend and delivered through APIs to any frontend application.

This API-First CMS approach gives developers greater flexibility. Instead of relying on templates built into the CMS, teams can create custom experiences using modern frameworks such as React, Angular, or Vue, or by building native mobile applications.

Headless systems align closely with modern Composable Architecture strategies, where organisations assemble best-of-breed technologies rather than relying on a single monolithic platform.

Despite sharing this common foundation, Pure Headless and Hybrid Headless architectures take different approaches to balancing flexibility and content management capabilities.

What Is a Pure Headless CMS?

A Pure Headless CMS focuses entirely on content storage, organisation, and delivery through APIs. As organisations modernise their enterprise content management platforms, many are adopting pure headless architectures to gain greater flexibility in how content is delivered across digital channels.

In this model, the CMS doesn't provide website rendering, page management, visual editing, or presentation tools. Content creators manage structured content, while developers build separate frontend applications that consume it via APIs.

The primary goal is to create a clean separation between content and presentation.

A Pure Headless CMS is particularly attractive for organisations with strong development teams and highly customised digital experiences. Since there are no restrictions imposed by a built-in presentation layer, developers have complete freedom to design user experiences across multiple channels.

This approach supports true Omnichannel Content Delivery because the same content repository can power websites, mobile apps, digital signage, voice assistants, and future channels that may not yet exist.

But this flexibility often comes with tradeoffs. Marketing teams may become dependent on developers for tasks that would otherwise be handled through visual editing tools. Content preview capabilities can also be limited compared to more integrated solutions.

What Is a Hybrid Headless CMS?

A Hybrid Headless CMS combines the API-driven capabilities of headless architecture with traditional CMS features.

Like a pure headless platform, content can be delivered through APIs to multiple channels. But hybrid systems also provide optional presentation capabilities, visual editing interfaces, page management tools, and content previews.

This dual approach allows organisations to support both developer-driven applications and marketer-friendly content management workflows.

A Hybrid Headless CMS, like Coremedia or Optimizely, enables teams to choose the most appropriate content delivery method for each use case. Some experiences can be delivered through APIs, while others can leverage built-in rendering capabilities.

For many enterprises, this balance reduces operational complexity while maintaining the flexibility needed for modern digital experiences.

Hybrid platforms are increasingly becoming a core component of broader Digital Experience Platform (DXP) strategies because they address both technical and business requirements.

Comparing Content Creation and Editorial Experience

One of the most significant differences in any Headless CMS Comparison involves the content authoring experience.

In a Pure Headless CMS environment, content creators typically work with structured content models. They create and manage content independently of how it appears on end-user devices.

While this approach encourages content reuse and consistency, it can make it difficult for editors to visualise the final experience. Preview functionality often requires additional development work.

Hybrid Headless CMS platforms usually offer richer editorial tools. Editors can preview content before publication, manage page layouts, and collaborate more effectively with marketing teams.

For enterprises with large editorial organisations, these capabilities can significantly improve Content Workflow Management and reduce friction between technical and non-technical stakeholders.

Organisations should carefully evaluate whether developer flexibility or editorial efficiency represents the higher priority.

Developer Flexibility and Customisation

When evaluating CMS Architecture options, developer flexibility remains a major consideration.

Pure Headless CMS platforms offer maximum freedom. Development teams can select any frontend technology, framework, or architecture without limitations imposed by the CMS.

This flexibility is particularly valuable for organisations building complex digital ecosystems with unique user experiences.

Developers can independently optimise performance, security, scalability, and user interfaces while leveraging APIs for content retrieval.

Hybrid platforms also support modern frontend frameworks and API-based delivery. But some organisations may perceive certain built-in capabilities as adding additional complexity or reducing architectural purity.

In practice, many Hybrid Headless CMS solutions still provide substantial developer flexibility while offering tools that simplify content management operations.

The best choice often depends on how much control developers require and how much autonomy content teams need.

Enterprise Content Governance and Compliance

Governance becomes increasingly important as organisations scale content production across regions, departments, and channels.

Enterprise CMS platforms must support approval workflows, permissions, auditing, version control, and regulatory compliance requirements.

Pure Headless CMS platforms can support governance, but many organisations must integrate additional tools to achieve comprehensive oversight.

Hybrid Headless CMS solutions often include advanced CMS Governance features directly within the platform.

These capabilities help organisations maintain consistency, enforce content standards, and manage risk across large content ecosystems.

For regulated industries such as finance, healthcare, and pharmaceuticals, governance capabilities can become a deciding factor when selecting an Enterprise CMS.

Organisations that prioritise compliance and oversight should carefully assess governance requirements during vendor evaluations.

Content Localisation and Global Operations

Global enterprises frequently manage content in dozens of languages and markets.

Content Localization is no longer limited to translation. It also involves regional customisation, legal compliance, cultural adaptation, and coordinated publishing schedules.

Pure Headless CMS platforms can support localisation through structured content models and API-based delivery. But localisation workflows may require additional integrations and custom development.

Hybrid systems often provide more comprehensive localisation management features, including translation workflows, language synchronisation, content previews, and market-specific publishing controls.

These capabilities streamline global content operations and reduce administrative overhead for multinational organisations.

As enterprises expand internationally, localisation support becomes a critical component of long-term content strategy.

Supporting Composable Architecture Initiatives

Many organisations are embracing Composable Architecture to improve agility and avoid vendor lock-in.

A composable approach allows businesses to assemble specialised tools for content management, personalisation, analytics, commerce, and customer engagement.

Pure Headless CMS platforms naturally align with composable strategies because they focus exclusively on content management and API delivery.

Hybrid platforms can also support composable environments while providing additional integrated capabilities.

The decision often depends on organisational maturity. Enterprises with sophisticated engineering teams may prefer assembling specialised components themselves. Organisations seeking faster implementation may benefit from the integrated capabilities offered by hybrid solutions.

Both approaches can successfully support modern composable ecosystems when implemented correctly.

Which Architecture Is Right for Your Enterprise?

There is no universal answer to the Pure Headless versus Hybrid Headless debate.

A Pure Headless CMS may be the right choice when an organisation prioritises developer flexibility, custom frontend experiences, and extensive omnichannel delivery requirements. It works particularly well for companies with mature engineering resources and highly specialised digital products.

A Hybrid Headless CMS may be the better option when marketing teams require visual editing, content previews, workflow automation, and governance capabilities. It can reduce operational complexity while still supporting modern API-driven delivery models.

Many enterprises ultimately discover that business requirements extend beyond technical architecture alone. Editorial productivity, governance, localisation, compliance, and long-term scalability often play equally important roles in platform selection.

Organisations evaluating enterprise content management platforms should consider not only current requirements but also future growth, emerging channels, and evolving customer expectations.

Conclusion

The evolution of digital experiences has transformed how enterprises approach content management. Traditional monolithic systems are giving way to more flexible architectures that support modern customer journeys across multiple channels.

Both Pure Headless CMS and Hybrid Headless CMS solutions offer significant advantages over legacy platforms, but they serve different organisational needs.

Pure headless architectures emphasise flexibility, customisation, and API-first development. Hybrid architectures balance those capabilities with stronger editorial experiences, governance controls, and content management functionality.

The most successful Enterprise Content Management strategies align technology choices with business objectives. By carefully evaluating developer needs, content operations, governance requirements, localisation demands, and composable architecture goals, organisations can select a CMS architecture that supports sustainable growth and exceptional digital experiences for years to come.

For organisations researching enterprise content management platforms, understanding these architectural differences is an essential first step toward building a scalable and future-ready digital ecosystem.

]]> <![CDATA[ How Large-Scale Platforms Handle Millions of Daily Transactions ]]> https://www.freecodecamp.org/news/how-large-scale-platforms-handle-millions-of-daily-transactions/ 6a2cfda7306003b984294a7b Sat, 13 Jun 2026 06:50:15 +0000 Every day, millions of people order food, stream videos, send messages, book rides, make payments, and shop online. Most of these actions take only a few seconds from the user's perspective. A user clicks a button, and the platform responds almost instantly.

Behind the scenes, however, these platforms are processing enormous numbers of transactions. A single popular application may handle thousands of requests every second and millions of transactions every day. Each transaction must be processed accurately, securely, and quickly.

In this article, we'll explore how large-scale platforms manage massive transaction volumes, the engineering challenges involved, and the architectural patterns developers use to build reliable systems.

What We'll Cover:

Why Transaction Volume Creates Unique Challenges

Handling a few hundred transactions per day is relatively straightforward. A single server and database can often manage the workload without difficulty. The challenge emerges as usage grows and systems begin serving thousands or even millions of users simultaneously.

Consider an online marketplace operating across multiple countries. At any given moment, thousands of users may be placing orders. Inventory must be updated in real time, payments must be processed accurately, notifications must be delivered, and fraud detection systems must evaluate transactions before approval. All of this happens within seconds.

At scale, even a minor delay can affect thousands of users. Systems must maintain low response times while preventing database bottlenecks, avoiding duplicate transactions, handling unexpected traffic spikes, and remaining reliable when failures occur.

To solve these problems, engineering teams rely on distributed systems and scalable architectural patterns.

Breaking Monoliths Into Services

Many successful platforms begin as monolithic applications where all functionality exists within a single codebase. While this approach works well during the early stages of growth, it can become increasingly difficult to scale as transaction volume increases.

To overcome this limitation, large platforms often adopt a service-oriented architecture. Instead of one application handling every responsibility, individual services are created for specific business functions such as user management, payments, inventory, notifications, and analytics.

A simplified order-processing workflow might look like this:

def create_order(user_id, product_id):
    inventory.reserve(product_id)

    payment_result = payment.charge(user_id)

    if payment_result.success:
        order.create(user_id, product_id)
        notification.send_confirmation(user_id)

    return payment_result

This separation allows each service to scale independently. If payment activity suddenly increases, engineers can allocate additional resources specifically to the payment service without affecting the rest of the platform. It also lets teams develop, deploy, and maintain services independently, improving both agility and reliability.

Using Load Balancers to Distribute Traffic

No single server can handle millions of daily transactions on its own. To distribute incoming requests efficiently, platforms place load balancers in front of their application servers.

Instead of connecting directly to a server, users send requests to a load balancer. The load balancer determines which server is best positioned to handle each request based on factors such as current load, availability, and health status.

A simplified architecture looks like this:

Users
   |
Load Balancer
   |
-------------------
|        |        |
Server1 Server2 Server3

If one server becomes overloaded or fails, traffic can be redirected to healthier servers. This improves both performance and availability. Modern cloud providers offer managed load-balancing solutions that automatically distribute traffic based on resource utilization and server health.

Why Databases Become Bottlenecks

Scaling application servers is often relatively easy. But databases frequently become the most significant bottleneck in transaction-heavy systems.

Every transaction ultimately requires reading or writing data. Consider an online task management platform where users complete tasks and receive rewards. Each completed task may trigger multiple database operations, including verification of task completion, updating account balances, recording transaction history, and generating audit logs.

As transaction volume grows, database performance becomes critical. One common solution is read replication. Instead of relying on a single database instance, platforms create multiple replicas that handle read requests while the primary database focuses on write operations.

The architecture may resemble the following:

Primary DB
     |
-------------------------
|         |            |
Replica1 Replica2 Replica3

By distributing read traffic across multiple replicas, platforms reduce pressure on the primary database and improve response times for users.

Caching Frequently Accessed Data

Not every request needs to reach the database. In fact, repeatedly querying the database for the same information can significantly increase infrastructure costs and response times.

To address this, platforms use caching systems such as Redis to store frequently accessed data in memory. Information such as user profiles, product details, and application settings often changes infrequently and can be retrieved directly from the cache.

Without caching:

user = database.get_user(user_id)

With caching:

user = cache.get(user_id)

if not user:
    user = database.get_user(user_id)
    cache.set(user_id, user)

Memory access is substantially faster than database queries. When a platform processes millions of requests every day, caching can dramatically improve performance while reducing backend load.

Processing Tasks Asynchronously

Users expect immediate responses. If every operation must finish before the system responds, applications quickly become sluggish under heavy load.

To improve responsiveness, large-scale systems separate critical user-facing actions from background processing tasks. Consider a payment transaction. The user needs confirmation that the payment was successful, but they don't need to wait for analytics updates, report generation, or email delivery.

A synchronous implementation might look like this:

process_payment()
send_email()
update_analytics()
generate_report()

A more scalable approach uses message queues:

process_payment()

queue.publish("send_email")
queue.publish("update_analytics")
queue.publish("generate_report")

Background workers consume these queued tasks and process them independently. This architecture improves user experience and enables systems to handle significantly larger transaction volumes.

Preventing Duplicate Transactions

One of the most important challenges in transaction processing is preventing duplicate execution.

Network interruptions can create situations where users unknowingly submit the same request multiple times. Imagine a customer making a purchase. The payment succeeds, but the confirmation never reaches the user's device because of a network failure. Believing the payment failed, the customer clicks the button again.

Without safeguards, the platform could charge the customer twice.

Many systems solve this problem through idempotency keys. A simplified implementation looks like this:

def process_payment(request_id, amount):

    if payment_exists(request_id):
        return existing_payment(request_id)

    payment = create_payment(request_id, amount)
    return payment

If the same request arrives again, the system returns the original result instead of processing a second payment. This pattern is widely used in financial services, payment gateways, and banking applications.

Monitoring Everything

As systems grow more complex, visibility becomes essential. Engineering teams can't effectively troubleshoot issues they can't observe.

Modern platforms collect metrics from every layer of their infrastructure. Engineers continuously monitor request latency, database response times, error rates, queue depth, CPU utilization, and memory consumption.

A simple monitoring rule might look like this:

if error_rate > 5:
    alert("High error rate detected")

Monitoring enables teams to identify problems before they impact users. It also provides valuable data for performance optimization and future capacity planning.

Preparing for Traffic Spikes

Traffic patterns are rarely predictable. An e-commerce platform may experience enormous demand during holiday sales, while a ticketing website can receive millions of requests within minutes when a popular event goes live.

To handle these surges, platforms rely on autoscaling. Cloud infrastructure can automatically add resources as demand increases and remove them when traffic subsides.

A simplified scaling rule might look like this:

if cpu_usage > 70:
    add_server()

Autoscaling helps maintain performance during peak periods while controlling infrastructure costs during quieter times.

Building for Failure

One of the most important principles in distributed systems is accepting that failures are inevitable.

Servers crash. Databases become unavailable. Networks experience interruptions. Rather than hoping these events never occur, large-scale platforms design systems that can continue operating when failures happen.

For example, payment systems often include retry logic:

for attempt in range(3):
    try:
        charge_customer()
        break
    except:
        continue

In addition, platforms implement redundancy by running multiple instances of critical components across different geographic regions and availability zones. If one component fails, another can take over with minimal disruption.

This strategy significantly improves availability and resilience.

The Importance of Consistency and Reliability

At scale, transaction processing isn't solely about speed. Accuracy is equally important.

Users may tolerate a slight delay, but they won't tolerate duplicate charges, missing funds, incorrect balances, or lost transactions. For this reason, large-scale transaction systems place a strong emphasis on consistency, auditing, logging, reconciliation, and recovery mechanisms.

Every transaction must be traceable. Every failure must be recoverable. These requirements become particularly important in industries such as finance, e-commerce, subscription billing, and task earning platforms where money and rewards move between users and businesses every day.

Conclusion

The ability to handle millions of daily transactions isn't the result of a single technology. It comes from combining multiple architectural principles that work together to create reliable, scalable systems.

Large-scale platforms distribute traffic across multiple servers, separate responsibilities into specialized services, cache frequently accessed data, process background work asynchronously, continuously monitor system health, and design for inevitable failures.

For developers, understanding these patterns provides valuable insight into how modern internet platforms operate behind the scenes. Whether you're building a payment processor, a SaaS platform, an online marketplace, or a task earning application, the same foundational principles apply.

As systems grow, scalability becomes less about writing more code and more about designing architecture that remains reliable under increasing demand. The platforms that succeed are the ones capable of delivering fast, accurate, and consistent transactions regardless of how many users arrive.

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

]]> <![CDATA[ How to Set Up OpenClaw and Design an A2A Plugin Bridge ]]> https://www.freecodecamp.org/news/openclaw-a2a-plugin-architecture-guide/ 69d542ca5da14bc70e7c1559 Tue, 07 Apr 2026 17:45:46 +0000 OpenClaw is getting attention because it turns a popular AI idea into something you can actually run yourself. Instead of opening one more browser tab, you run a Gateway on your own machine or server and connect it to communication tools you already use.

That matters because OpenClaw is self-hosted, multi-channel, open source, and built around agent workflows such as sessions, tools, plugins, and multi-agent routing. It feels less like a toy chatbot and more like an operator-controlled agent runtime.

In this guide, you'll do three things. First, you'll learn what OpenClaw is and why developers are paying attention to it. Second, you'll get it running the beginner-friendly way through the dashboard. Third, you'll walk through an original design contribution: a proposed OpenClaw-to-A2A plugin architecture and a proof-of-concept relay that shows how OpenClaw’s session model could map to the A2A protocol.

That last part is important, so I want to frame it carefully. The A2A integration in this article is not presented as a built-in OpenClaw feature. It's a documented architecture proposal built on top of the extension points OpenClaw already exposes.

Prerequisites

This guide is beginner-friendly for OpenClaw itself, but it assumes a few basics so you can follow the architecture and proof-of-concept sections comfortably.

Before you continue, you should be familiar with:

  • Basic JavaScript or Node.js (reading and running scripts)

  • How HTTP APIs work (requests, responses, JSON payloads)

  • Using a terminal to run commands

  • High-level concepts like services, APIs, or microservices

You don't need prior experience with OpenClaw or A2A. The setup steps walk through everything you need to get started.

Table of Contents

  1. What OpenClaw Is

  2. Why OpenClaw Is Getting So Much Attention

  3. What the A2A Protocol Is

  4. How OpenClaw and A2A Relate

  5. What You Need Before You Start

  6. Install OpenClaw

  7. Run the Onboarding Wizard

  8. Check the Gateway and Open the Dashboard

  9. Use OpenClaw as a Private Coding Assistant

  10. Understand Multi Agent Routing

  11. Where A2A Could Fit Later

  12. A Proposed OpenClaw to A2A Plugin Architecture

  13. Build the Proof of Concept Relay

  14. How the Proof of Concept Maps to a Real OpenClaw Plugin

  15. Security Notes Before You Go Further

  16. Final Thoughts

What OpenClaw Is

According to the official docs, OpenClaw is a self-hosted gateway that connects chat apps like WhatsApp, Telegram, Discord, iMessage, and a browser dashboard to AI agents.

That wording is useful because it tells you where OpenClaw sits in the stack. It's not just a model wrapper. It's a Gateway that handles sessions, routing, and app connections, while agents, tools, plugins, and providers do the actual work.

Here is the simplest mental model:

Diagram showing OpenClaw architecture where multiple chat apps and a browser dashboard connect to a central Gateway, which routes requests to different agents that use model providers and tools.

If you're new to the project, this is the practical way to think about it:

  • your chat apps are the front door

  • the Gateway is the traffic and control layer

  • the agent is the reasoning layer

  • the model provider and tools are what let the agent actually do work

That's one reason OpenClaw feels different from a normal browser-only assistant.

Why Developers Are Paying Attention to OpenClaw

OpenClaw is getting a lot of attention for a few reasons.

The first reason is control. The docs position OpenClaw as self-hosted and multi-channel, which means you can run it on your own machine or server instead of depending on a fully hosted assistant.

The second reason is that OpenClaw already looks like an agent platform. The docs talk about sessions, plugins, tools, skills, multi-agent routing, and ACP-backed external coding harnesses. That's a much richer story than “ask a model a question in a web page.”

The third reason is workflow fit. A lot of people don't want another inbox. They want an assistant that can live in the tools they already check every day.

There's also a broader industry trend behind the hype. Developers are actively looking for ways to connect multiple agents and multiple tools without giving up visibility into what's happening. OpenClaw sits directly in that conversation.

What the A2A Protocol Is

A2A, short for Agent2Agent, is an open protocol for communication between agent systems. The A2A specification says its purpose is to help independent agent systems discover each other, negotiate interaction modes, manage collaborative tasks, and exchange information without exposing internal memory, tools, or proprietary logic.

That last point matters. A2A is about interoperability between agent systems, not about exposing all of one agent's internals to another.

A2A introduces a few core concepts that are worth learning early:

  • Agent Card: a JSON description of the remote agent, its URL, skills, capabilities, and auth requirements

  • Task: the main unit of remote work

  • Artifact: the output of a task

  • Context ID: a stable interaction boundary across multiple related turns

A2A tasks follow a fairly clean lifecycle:

State diagram illustrating the A2A task lifecycle including submitted, working, input required, completed, failed, rejected, and canceled states..

The A2A docs also explain that A2A and MCP are complementary, not competing. A2A is for agent-to-agent collaboration. MCP is for agent-to-tool communication.

That distinction is useful when you compare A2A with OpenClaw, because OpenClaw already has strong local tool and session concepts.

How OpenClaw and A2A Relate

OpenClaw and A2A are not the same thing, but they line up in interesting ways.

OpenClaw already documents several features that point in a multi-agent direction:

But it's still important to stay precise here.

OpenClaw documents ACP, plugins, and local multi-agent coordination today. The docs I checked do not describe native A2A support as a first-class built-in capability.

That means the honest claim is this:

OpenClaw can be meaningfully connected to A2A in theory because the architectural pieces line up, but the A2A bridge still has to be built.

ACP versus A2A

ACP and A2A solve different problems.

ACP in OpenClaw today is about bridging an IDE or coding client to a Gateway-backed session.

A2A is about one agent system talking to another agent system across a protocol boundary.

Diagram showing A2A interaction where an OpenClaw agent communicates through a plugin to discover a remote agent via an Agent Card and send tasks for execution. Diagram showing ACP flow where an IDE or coding client connects through an OpenClaw ACP bridge to a Gateway-backed session.

That difference is one reason I prefer the phrase plugin bridge here instead of native A2A support.

What You Need Before You Start

The easiest first run does not require WhatsApp, Telegram, or Discord.

The OpenClaw onboarding docs say the fastest first chat is the dashboard. That makes this a much more approachable beginner setup.

Before you start, you'll need:

  1. Node 24 if possible, or Node 22.16+ for compatibility

  2. an API key for the model provider you want to use

  3. If you're on Windows, WSL2 is the recommended path for the full experience. Native Windows works for core CLI and Gateway flows, but the docs call out caveats and position WSL2 as the more stable setup.

  4. about five minutes for the first dashboard-based run

Step 1: Install OpenClaw

The official getting-started page recommends the installer script.

On macOS, Linux, or WSL2, run:

curl -fsSL https://openclaw.ai/install.sh | bash

On Windows PowerShell, the docs show this:

iwr -useb https://openclaw.ai/install.ps1 | iex

If you're on Windows, the platform docs recommend installing WSL2 first:

wsl --install

Then open Ubuntu and continue with the Linux commands there.

Step 2: Run the Onboarding Wizard

Once the CLI is installed, run the onboarding wizard.

openclaw onboard --install-daemon

The onboarding wizard is the recommended path in the docs. It configures auth, gateway settings, optional channels, skills, and workspace defaults in one guided flow.

The most beginner-friendly choice is to keep the first run simple. Don't worry about chat apps yet. Get the local Gateway working first.

Step 3: Check the Gateway and Open the Dashboard

After onboarding, verify that the Gateway is running.

openclaw gateway status

Then open the dashboard:

openclaw dashboard

The docs call this the fastest first chat because it avoids channel setup. It's also the safest way to start, because the dashboard is local and the OpenClaw docs clearly say the Control UI is an admin surface and should not be exposed publicly.

The beginner setup flow looks like this:

Sequence diagram showing OpenClaw setup flow from installation and onboarding to starting the Gateway and opening the dashboard for the first chat.

If you can chat in the dashboard, your day-zero setup is working.

Step 4: Use OpenClaw as a Private Coding Assistant

The best first use case is not to drop OpenClaw into a public group chat.

Use it as a private coding assistant in the dashboard.

For example, try a prompt like this:

I am building a small Node.js utility that reads Markdown files and generates a table of contents. Turn this idea into a project plan, a README outline, and the first five implementation tasks.

That kind of prompt is ideal for a first run because it gives you something concrete back right away.

You can also use it to:

  1. turn rough notes into a plan,

  2. summarize a bug report into action items,

  3. draft a README,

  4. propose a folder structure, or

  5. write a safe first implementation checklist.

That is already enough to make OpenClaw useful before you touch any advanced protocol work.

Step 5: Understand Multi Agent Routing

Once the basic setup is working, it helps to understand OpenClaw’s local multi-agent model.

The docs describe multi-agent routing as a way to run multiple isolated agents in one Gateway, with separate workspaces, state directories, and sessions.

That means you can imagine setups like this:

  • a personal assistant

  • a coding assistant

  • a research assistant

  • an alerts assistant

OpenClaw already has a model for that:

Diagram illustrating OpenClaw multi-agent routing where incoming messages are matched to different agents such as main, coding, and alerts, each with separate sessions.

You don't need to set this up on day one.

But it matters for the A2A discussion, because once you understand how OpenClaw routes work between local agents, it becomes much easier to think about routing work to remote agents through a protocol like A2A.

Where A2A Could Fit Later

A2A could fit into OpenClaw in two broad ways.

Option 1: OpenClaw as an A2A Client

In this model, OpenClaw stays your personal edge assistant.

It receives a request from the dashboard or a chat app, decides the task needs a specialist, discovers a remote A2A agent through an Agent Card, sends the task, waits for updates or artifacts, and translates the result back into a normal OpenClaw reply.

Diagram showing OpenClaw acting as an A2A client, delegating tasks from a local session to a remote agent via an Agent Card and returning results to the user.

This is the cleaner story for a personal assistant. OpenClaw stays the front door, and A2A becomes a delegation path behind the scenes.

Option 2: OpenClaw as an A2A Server

In this model, OpenClaw exposes some of its own capabilities to other agents.

A plugin could theoretically publish an A2A Agent Card, advertise a narrow skill set, accept A2A tasks, and map those tasks into OpenClaw sessions or sub-agent runs.

That's technically plausible because the plugin system can register HTTP routes, tools, Gateway methods, and background services.

It's also the riskier direction for a personal assistant, which is why I think client-first is the right starting point.

A Proposed OpenClaw to A2A Plugin Architecture

This section is my original contribution in the article.

I think the cleanest first architecture is not a full bidirectional bridge. It's a narrow outbound delegation plugin that lets OpenClaw call a small allowlist of remote A2A agents.

The design goal is simple:

Reuse OpenClaw for user-facing conversations and local tool access, but use A2A only when a remote specialist agent is the best place to do the work.

Here is the architecture I would start with:

Architecture diagram of an OpenClaw-to-A2A plugin showing components such as delegation tool, policy engine, Agent Card cache, session-to-task mapper, task poller, and remote A2A agent.

Why This Design is a Good Fit for OpenClaw

This proposal is grounded in extension points OpenClaw already documents.

A plugin can register:

  • an agent tool for delegation,

  • a Gateway method for health and diagnostics,

  • an HTTP route for future callbacks or webhook verification, and

  • a background service for cache warming, task subscriptions, or cleanup.

That means the bridge doesn't have to modify OpenClaw core to be credible.

The Mapping Table

The most important design decision is how to map OpenClaw’s session model to A2A’s task model.

Here is the mapping I recommend:

OpenClaw concept A2A concept Why this mapping works
sessionKey contextId A single OpenClaw conversation should keep a stable remote context across related delegated turns
one delegated remote call one Task each remote specialization request becomes a discrete unit of work
plugin tool call SendMessage the delegation tool is the natural point where the local agent crosses the protocol boundary
remote output Artifact A2A wants task outputs returned as artifacts rather than chat-only replies
plugin HTTP route callback or future push handler gives you a place to verify webhooks if you later adopt async push
Gateway method status endpoint gives operators a direct way to inspect relay health without going through the model
background service polling or cache work keeps asynchronous and maintenance work out of the tool call path

This is the key architectural claim in the article:

Treat the OpenClaw session as the long-lived conversational boundary, and treat each remote A2A task as one delegated execution inside that boundary.

That preserves both sides cleanly.

The Design in One Sentence

The a2a_delegate tool should:

  1. resolve an allowlisted remote Agent Card,

  2. reuse an existing A2A contextId for the current sessionKey when possible,

  3. create a fresh remote Task for the new delegated turn,

  4. normalize remote artifacts back into a simple local answer, and

  5. never expose the whole OpenClaw Gateway directly to the public internet.

I like this design because it is incremental, testable, and consistent with OpenClaw’s personal-assistant trust model.

Build the Proof of Concept Relay

To make the architecture concrete, I built a small proof-of-concept relay.

https://github.com/natarajsundar/openclaw-a2a-secure-agent-runtime

It's intentionally small. It doesn't try to become a full production plugin. Instead, it proves the hardest conceptual part of the bridge: how to map one OpenClaw session to a reusable A2A context while creating a fresh A2A task per delegated turn.

Here's the repository layout:

openclaw-a2a-secure-agent-runtime/
├── README.md
├── package.json
├── examples/
│   └── openclaw-plugin-entry.example.ts
├── src/
│   ├── a2a-client.mjs
│   ├── agent-card-cache.mjs
│   ├── demo.mjs
│   ├── mock-remote-agent.mjs
│   ├── openclaw-a2a-relay.mjs
│   ├── session-task-map.mjs
│   └── utils.mjs
└── test/
    └── relay.test.mjs

The PoC does six things:

  1. fetches a remote Agent Card from /.well-known/agent-card.json,

  2. caches it with simple ETag revalidation,

  3. records local sessionKey to remote contextId mappings,

  4. sends an A2A SendMessage request,

  5. polls GetTask until the task finishes, and

  6. converts the remote artifact into a local text answer.

Run the Demo

The repo uses only built-in Node.js modules.

cd openclaw-a2a-secure-agent-runtime
npm run demo

The demo spins up a mock remote A2A server, delegates one task, delegates a second task from the same local session, and shows that the same remote contextId is reused.

The Core Relay Idea

This is the important logic in plain English:

  1. look up the most recent remote mapping for the current OpenClaw sessionKey

  2. reuse the old contextId if one exists

  3. create a fresh A2A Task for the new request

  4. poll until that task becomes TASK_STATE_COMPLETED

  5. turn the returned artifact into a normal text result that OpenClaw can send back to the user

That makes the bridge predictable.

Here's a shortened version of the relay logic:

const previous = await sessionTaskMap.latestForSession(sessionKey, remoteBaseUrl);
const contextId = previous?.contextId ?? crypto.randomUUID();

const sendResult = await client.sendMessage({
  text,
  contextId,
  metadata: {
    openclawSessionKey: sessionKey,
    requestedSkillId: skillId,
  },
});

let task = sendResult.task;
while (!isTerminalTaskState(task.status?.state)) {
  await sleep(pollIntervalMs);
  task = await client.getTask(task.id);
}

return {
  contextId,
  taskId: task.id,
  answer: taskArtifactsToText(task),
};

That's the heart of the design.

Why This Repo is a Useful Proof of Concept

A lot of “integration” articles stay too abstract. This repo avoids that problem in three ways.

First, it makes the session-to-context mapping explicit.

Second, it includes a mock remote A2A agent so you can test the flow without needing a large external setup.

Third, it includes a test that checks the most important invariant: repeated delegations from one local OpenClaw session reuse the same A2A context.

That is the piece I most wanted to make concrete, because it is where architecture turns into implementation.

How the Proof of Concept Maps to a Real OpenClaw Plugin

The proof of concept is the relay core.

A real OpenClaw plugin would wrap that relay with four extension surfaces that the OpenClaw docs already describe.

1: A Delegation Tool

This is the main entry point.

A plugin would register an optional tool like a2a_delegate so the local agent can explicitly choose to delegate work.

That tool should be optional, not always-on, because remote delegation is a side effect and should be easy to disable.

2: A Gateway Method for Diagnostics

A method like a2a.status would let you inspect whether the relay is healthy, which remote cards are cached, and whether any tasks are still being tracked.

That is much better than asking the model to “tell me if the bridge is healthy.”

3: A Plugin HTTP Route

You may not need this on day one.

But once you move beyond polling and want push-style callbacks or webhook verification, a plugin route gives you the right boundary for that work.

4: A Background Service

A small service is a clean place to do cache warming, cleanup, or later subscription handling.

That keeps the tool path focused on delegation instead of maintenance work.

If I were turning this into a real plugin package, I would sequence the work in this order:

  1. wrap the relay in registerTool,

  2. add a small config schema with an allowlist of remote agents,

  3. add a2a.status,

  4. keep polling as the first async model,

  5. add a callback route only if a real use case needs it.

That is the most practical path from theory to a real extension.

I tested the relay flow locally with the mock remote agent and confirmed that repeated delegations from the same local session reused the same remote contextId.

Security Notes Before You Go Further

This is the section you should not skip.

The OpenClaw security docs explicitly say the project assumes a personal assistant trust model: one trusted operator boundary per Gateway. They also say a shared Gateway for mutually untrusted or adversarial users is not the supported boundary model.

That has a direct consequence for A2A.

A2A is designed for communication across agent systems and organizational boundaries. That is powerful, but it is also a different threat model from a single private OpenClaw deployment.

So the safer design is not this:

  • expose your personal OpenClaw Gateway publicly,

  • let arbitrary remote agents reach it,

  • and hope the tool boundaries are enough.

The safer design is closer to this:

Diagram illustrating separation between a private OpenClaw deployment and an external A2A interoperability boundary, highlighting secure delegation through a controlled relay.

This diagram shows two separate trust boundaries.

On the left is your private OpenClaw deployment. This includes your Gateway, your sessions, your workspace, and any credentials or tools your agent can access. This boundary is designed for a single trusted operator.

On the right is the external A2A ecosystem, where remote agents live. These agents may belong to other teams or organizations and operate under different security assumptions.

The key idea is that communication between these two sides should happen through a controlled relay layer, not by directly exposing your OpenClaw Gateway. The relay enforces allowlists, limits what data is sent out, and ensures that remote agents cannot directly access your local tools or state.

This separation lets you experiment with agent interoperability while keeping your personal assistant environment safe.

In plain English, keep your personal assistant boundary private.

If you experiment with A2A, treat that as a separate exposure boundary with its own allowlists, auth, and operational controls.

That is why the proof-of-concept relay in this article starts with an explicit remote allowlist.

Why This Design and Not the Other One?

A natural question is why this article proposes an outbound-only A2A bridge first, instead of immediately building a full bidirectional or server-style integration.

The short answer is that OpenClaw’s current design is centered around a personal assistant trust boundary, where one operator controls the Gateway, sessions, and tools. Introducing external agents into that environment requires careful control over what is exposed.

Starting with outbound delegation gives you a safer and more incremental path.

Outbound-only first means:

  • preserving the personal-assistant trust boundary, so your local OpenClaw deployment remains private and operator-controlled

  • avoiding exposing the OpenClaw Gateway as a public A2A server before you have strong auth, policy, and monitoring in place

  • allowing you to test remote delegation patterns (Agent Cards, tasks, artifacts) without committing to full interoperability complexity

  • keeping OpenClaw as the user-facing control plane, while remote agents act as optional specialists

This approach follows a common systems design pattern: start with controlled outbound integration, validate behavior and constraints, and only then consider expanding to inbound or bidirectional communication.

In practice, this means you can experiment with A2A safely, learn how the models fit together, and evolve the system without introducing unnecessary risk early on.

Final Thoughts

OpenClaw is worth learning because it gives you a self-hosted assistant that can live in the communication tools you already use.

The simplest beginner path is still the right one:

  1. install it,

  2. run onboarding,

  3. check the Gateway,

  4. open the dashboard,

  5. try one private workflow.

That is already a real end-to-end setup.

A2A belongs in the conversation because it gives you a credible way to connect OpenClaw to remote specialist agents later.

But the most important thing in this article isn't the buzzword. It's the boundary design.

If you keep OpenClaw as the private user-facing edge and use a narrow plugin bridge for outbound delegation, the OpenClaw session model and the A2A task model can fit together cleanly.

That is the architectural idea I wanted to make concrete here.

Diagram Attribution

All diagrams in this article were created by the author specifically for this guide.

Further Reading

]]> <![CDATA[ How to Build AI Agents That Remember User Preferences (Without Breaking Context) ]]> https://www.freecodecamp.org/news/how-to-build-ai-agents-that-remember-user-preferences-without-breaking-context/ 698cc32db8fec0245bd9996d Wed, 11 Feb 2026 17:58:05 +0000 Why Personalization Breaks Most AI Agents

Personalization is one of the most requested features in AI-powered applications. Users expect an agent to remember their preferences, adapt to their style, and improve over time.

In practice, personalization is unfortunately also one of the fastest ways to break an otherwise working AI agent.

Many agents start with a simple idea: keep adding more conversation history to the prompt. This approach works for demos, but it quickly fails in real applications. Context windows grow too large. Irrelevant information leaks into decisions. Costs increase. Debugging becomes nearly impossible.

If you want a personalized agent that survives production, you need more than a large language model. You need a way to connect the agent to tools, manage multi-step workflows, and store user preferences safely over time – without turning your system into a tangled mess of prompts and callbacks.

In this tutorial, you’ll learn how to design a personalized AI agent using three core building blocks:

  • Agent Development Kit (ADK) to orchestrate agent reasoning and execution

  • Model Context Protocol (MCP) to connect tools with clear boundaries

  • Long-term memory to store preferences without polluting context

Rather than focusing on setup commands or vendor-specific walkthroughs, we'll focus on the architectural patterns that make personalized agents reliable, debuggable, and maintainable.

User preferences influence an AI agent’s personalized response

Figure 1 — Personalization influences agent responses

Table of Contents

Prerequisites

To follow along with this tutorial, you should have:

  • Basic familiarity with Python

  • A general understanding of how large language models work

  • Optional: a Google Cloud account if you want to run an end-to-end demo. Otherwise, you can follow the architecture and code patterns locally with stubs. We’ll avoid deep infrastructure setup and focus on design patterns rather than deployment mechanics.

You don’t need prior experience with ADK or MCP. I’ll introduce each concept as it appears.

What “Personalized” Means in a Real AI Agent

An AI agent accesses external tools through a protocol boundary/control layer

Figure 2 — Keep preferences out of the prompt: agent ↔ tools across a protocol boundary

Before writing any code, it’s important to define what personalization means in an AI agent.

Personalization is not the same as “remembering everything.” In practice, agent state usually falls into three categories:

  1. Short-term context: Information needed to complete the current task. This belongs in the prompt.

  2. Session state: Temporary decisions or selections made during a workflow. This should be structured and scoped to a session.

  3. Long-term memory: Durable user preferences or facts that should persist across sessions.

Three panels comparing short-term context, session state, and long-term memory

Figure 3 — Three kinds of agent state: context (now), session (today), memory (always)

Most problems happen when these categories are mixed together.

If you store long-term preferences directly in the prompt, the agent’s behavior becomes unpredictable. If you store everything permanently, memory grows without bounds. If you don’t scope memory at all, unrelated sessions start influencing each other.

A well-designed, personalized agent treats memory as a first-class system component, not as extra text added to a prompt.

In the next section, we'll look at how to structure the agent so these concerns stay separated.

By the end of this tutorial, you’ll understand how to design a personalized AI agent that uses long-term memory safely, connects to tools through clear boundaries, and remains debuggable as it grows.

How the Agent Architecture Fits Together

Reference architecture showing a user, an AI agent core, tools, a memory service, and an orchestration runtime

Figure 4 — Reference architecture: agent core + tools + memory service + orchestration runtime

The above diagram shows a high-level, personalized AI agent architecture. In it, an agent core handles reasoning and planning while interacting with a tool interface layer, a long-term memory service, and an orchestration runtime.

Let’s now understand the moving parts of a personalized agent and how they interact.

At a high level, the system has four responsibilities:

  1. Reasoning – deciding what to do next

  2. Execution – calling tools and services

  3. Memory – storing and retrieving long-term preferences

  4. Boundaries – controlling what the agent is allowed to do

A common mistake you’ll see is to blur these responsibilities together. For example, letting the model decide when to write memory, or allowing tools to execute actions without clear constraints.

Instead, you'll design the system so each responsibility has a clear owner. The core components look like this:

  • Agent core: Handles reasoning and planning

  • Tools: Perform external actions (read or write)

  • MCP layer: Defines how tools are exposed and invoked

  • Memory services: Store long-term user data safely

ADK sits at the center, orchestrating how requests flow between these components. The model never directly talks to databases or services. It reasons about actions, and ADK coordinates execution.

This separation makes the system easier to reason about, debug, and extend.

How to Design the Agent Core with ADK

Before we dive in, a quick note on what ADK is.

Agent Development Kit (ADK) is an agent orchestration framework – the glue code between a large language model and your application. Instead of treating the model as a black box that directly “does things”, ADK helps you structure the agent as a system:

  • The model focuses on reasoning (turning user intent, context, and memory into a structured plan)

  • Your runtime stays in control of execution (deciding which tools can run, how they run, and what gets logged or persisted)

In other words, ADK is what lets you take tool calling and multi-step workflows out of a giant prompt and turn them into a maintainable and testable architecture. In this tutorial, we’ll use ADK to refer to that orchestration layer. The same patterns apply if you use a different agent framework.

Note: The following code snippets are simplified reference examples intended to illustrate architectural patterns. They’re not production-ready drop-ins.

Once you understand the architecture, you can start designing the agent core. The agent core is responsible for reasoning, not execution.

A helpful mental model is to think of the agent as a planner, not a doer. Its role is to interpret the user’s goal, consider available context and memory, and produce a structured plan that can later be executed in a controlled way.

To make this concrete, the following example shows how an agent can translate user input and memory into an explicit plan. In practice, ADK orchestrates this using a large language model, but the important idea is that the output is structured intent, not side effects.

# Reference example for illustration.

from dataclasses import dataclass
from typing import List, Dict, Any

@dataclass
class Step:
    tool: str
    args: Dict[str, Any]

@dataclass
class Plan:
    goal: str
    steps: List[Step]

def build_plan(user_text: str, memory: Dict[str, Any]) -> Plan:
    # In practice, the LLM produces this structure via ADK orchestration.
    goal = f"Help user: {user_text}"
    steps = []
    if memory.get("prefers_short_answers"):
        steps.append(Step(tool="set_style", args={"verbosity": "low"}))
    steps.append(Step(tool="search_docs", args={"query": user_text}))
    steps.append(Step(tool="summarize", args={"max_bullets": 5}))
    return Plan(goal=goal, steps=steps)

This example illustrates an important constraint: the agent produces a plan, but it doesn’t execute anything directly.

The agent decides what should happen and in what order, while ADK controls when and how each step runs. This separation lets you inspect, test, and reason about decisions before they result in real-world actions.

When personalization is involved, this distinction becomes critical. Preferences may influence planning, but execution should remain tightly controlled by the runtime.

Again, we can consider the agent to be a planner, not a doer.

It should not:

  • Perform side effects directly

  • Write to databases

  • Call external APIs without supervision

In ADK, this separation is natural. The agent produces intents and tool calls, while the runtime controls how and when those calls are executed.

This design has two major benefits:

  1. Safety – you can restrict which tools the agent can access

  2. Debuggability – you can inspect decisions before execution

When personalization is involved, this becomes even more important. Preferences influence reasoning, but execution should remain tightly controlled.

How to Connect Tools Safely with MCP

Tool call routed through a control layer with request, validation, execution, and response steps.

Figure 5 — Tool calls with guardrails: request → validate → execute → respond

Tools are how agents interact with the real world. They fetch data, generate artifacts, and sometimes perform actions with side effects.

Without clear boundaries, tool usage quickly becomes a source of fragility. Hardcoded API calls leak into prompts, tools evolve independently, and agents gain more authority than intended.

To avoid these problems, tools should be explicitly registered and invoked through a narrow interface. The following example shows a simple tool registry pattern that mirrors how MCP exposes tools to an agent without tightly coupling it to implementations.

# Reference example (pseudocode for illustration)

from typing import Callable, Dict, Any

ToolFn = Callable[[Dict[str, Any]], Dict[str, Any]]

TOOLS: Dict[str, ToolFn] = {}

def register_tool(name: str):
    def decorator(fn: ToolFn):
        TOOLS[name] = fn
        return fn
    return decorator

@register_tool("search_docs")
def search_docs(args: Dict[str, Any]) -> Dict[str, Any]:
    query = args["query"]
    # Replace with your MCP client call (or local tool implementation).
    return {"results": [f"doc://example?q={query}"]}

def invoke_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
    if name not in TOOLS:
        raise ValueError(f"Tool not allowed: {name}")
    return TOOLS[name](args)

The Model Context Protocol (MCP) provides a clean way to formalize this pattern. You can think of MCP the same way operating systems treat system calls.

An application does not directly manipulate hardware. Instead, it requests operations through well-defined system calls. The kernel decides whether the operation is allowed and how it executes.

In the same way, the agent knows what capabilities exist, MCP defines how those capabilities are invoked, and the runtime controls when and whether they execute.

This separation prevents several common problems, including hardcoded API details in prompts, unexpected breakage when tools change, and agents performing unrestricted side effects.

When designing tools, it helps to classify them by risk: read tools for safe queries, generate tools for planning or synthesis, and commit tools for irreversible actions. In a personalized agent, commit tools should be rare and tightly guarded.

Observability around tool calls using logs, traces, and timing across decision points

Figure 6 — Observability around tool calls: logs, traces, timing, decision points

How to Add Long-Term Memory Without Polluting Context

Memory candidates extracted from user input, filtered and validated, then stored asynchronously

Figure 7 — Memory admission pipeline: extract → filter/validate → persist asynchronously

Memory is where personalization either succeeds or fails.

You can start by storing everything the user says and feed it back into the prompt. This works briefly, then collapses under its own weight as context grows, costs rise, and behavior becomes unpredictable.

A better approach is to treat memory as structured, curated data so you can control what the agent remembers and why with clear admission rules. Before persisting anything, the system should explicitly decide whether the information is worth remembering. The following function demonstrates a simple memory admission policy.

# Simplified Reference Only
from typing import Optional, Dict, Any

def memory_candidate(user_text: str) -> Optional[Dict[str, Any]]:
    text = user_text.lower()

    # Durable
    if "for this session" in text or "ignore after" in text:
        return None

    # Reusable
    if "my preferred language is" in text:
        return {"type": "preference", "key": "language", "value": user_text.split()[-1]}

    # Safe (basic example; add PII checks for your use case)
    if "password" in text or "ssn" in text:
        return None

    return None  # default: don’t store

This policy encodes three questions every memory candidate must answer:

  • Is it durable? Will it still matter in the future?

  • Is it reusable? Will it influence future decisions meaningfully?

  • Is it safe to persist? Does it avoid sensitive or session-specific data?

Only information that passes all three checks should become long-term memory. In practice, this usually includes stable preferences and long-lived constraints, not temporary instructions or intermediate reasoning.

Even if your admission rules are solid, long-term memory introduces governance requirements:

  • User control: allow users to view, export, and delete stored preferences at any time.

  • Sensitive data handling: never store secrets/PII. Run PII detection on every memory candidate (and consider redaction).

  • Retention + consent: use explicit consent for persistent memory and apply retention windows (TTL) so memory expires unless it’s still useful.

  • Security + auditability: encrypt at rest, restrict access by service identity, and keep an audit log of memory writes/updates.

Memory writes should also be asynchronous. The agent should never block while persisting memory, which keeps interactions responsive and avoids coupling reasoning to storage latency.

How the End-to-End Agent Flow Works

End-to-end flow showing user input, agent reasoning, tool invocation, and memory updates with feedback loops

Figure 8 — End-to-end request lifecycle: user input → plan → tools → memory updates

At this point, you can trace exactly how memory and tools interact during a single request. With the individual components in place, it’s helpful to see how they work together during a single request. The following example walks through the full lifecycle of a personalized interaction, from user input to response.

# Reference example (pseudocode for illustration)

def handle_request(user_id: str, user_text: str) -> str:
    memory = memory_store.get(user_id)  # e.g., {"prefers_short_answers": True}
    plan = build_plan(user_text, memory)

    tool_outputs = []
    for step in plan.steps:
        out = invoke_tool(step.tool, step.args)
        tool_outputs.append({step.tool: out})

    response = render_response(goal=plan.goal, tool_outputs=tool_outputs, memory=memory)

    cand = memory_candidate(user_text)
    if cand:
        # Never block the user on storage.
        memory_store.write_async(user_id, cand)
    return response

At a high level, the flow looks like this:

  1. The user sends a message.

  2. Relevant long-term memory is retrieved.

  3. The agent reasons about the request and produces a plan.

  4. ADK invokes tools through MCP as needed.

  5. Results flow back to the agent.

  6. The agent decides whether new information should be persisted.

  7. Memory is written asynchronously.

  8. The final response is returned to the user.

Notice what does not happen: the model does not directly write memory, tools do not execute without coordination, and context does not grow without bounds. This structure keeps personalization controlled and predictable.

Common Pitfalls You’ll Hit (and How to Avoid Them)

Even with a solid architecture, there are a few failure modes that show up repeatedly in real systems. Many of them stem from allowing agents to perform irreversible actions without explicit checks.

The following example shows a simple guardrail for commit-style tools that require approval before execution.

# Reference example (pseudocode for illustration)

def invoke_commit_tool(name: str, args: Dict[str, Any], approved: bool) -> Dict[str, Any]:
    if not approved:
        # Require explicit confirmation or policy approval before side effects.
        return {"status": "blocked", "reason": "commit tools require approval"}

    # For example: create_ticket, send_email, submit_order, update_record
    return invoke_tool(name, args)

This pattern forces a clear decision point before side effects occur. It also creates an audit trail that explains why an action was allowed or blocked.

Other common pitfalls include over-personalization, leaky memory that persists session-specific data, uncontrolled tool growth, and debugging blind spots caused by unclear boundaries. If you see these symptoms, it usually means responsibilities are not clearly separated.

What You Learned and Where to Go Next

Personalized AI agents are powerful, but they require discipline. The key insight is that personalization is a systems problem, not a prompt problem.

By separating reasoning from execution, structuring memory carefully, and using protocols like MCP to enforce boundaries, you can build agents that scale beyond demos and remain maintainable in production.

As you extend this system, resist the urge to add “just one more prompt tweak.” Instead, ask whether the change belongs in memory, tools, or orchestration.

That mindset will save you time as your agent grows in complexity.

If you’d like to continue the conversation, you can find me on LinkedIn.

*All diagrams in this article were created by the author for educational purposes.

]]> <![CDATA[ How to Use the Singleton Design Pattern in Flutter: Lazy, Eager, and Factory Variations ]]> https://www.freecodecamp.org/news/how-to-use-the-singleton-design-pattern-in-flutter-lazy-eager-and-factory-variations/ 69740b7bc3e68b8de44a179f Fri, 23 Jan 2026 23:59:55 +0000 In software engineering, sometimes you need only one instance of a class across your entire application. Creating multiple instances in such cases can lead to inconsistent behavior, wasted memory, or resource conflicts.

The Singleton Design Pattern is a creational design pattern that solves this problem by ensuring that a class has exactly one instance and provides a global point of access to it.

This pattern is widely used in mobile apps, backend systems, and Flutter applications for managing shared resources such as:

  • Database connections

  • API clients

  • Logging services

  • Application configuration

  • Security checks during app bootstrap

In this article, we'll explore what the Singleton pattern is, how to implement it in Flutter/Dart, its variations (eager, lazy, and factory), and physical examples. By the end, you'll understand the proper way to use this pattern effectively and avoid common pitfalls.

Table of Contents

  1. Prerequisites

  2. What is the Singleton Pattern?

  3. How to Create a Singleton Class

  4. Factory Constructors in the Singleton Pattern

  5. When Not to Use a Singleton

  6. Conclusion

Prerequisites

Before diving into this tutorial, you should have:

  1. Basic understanding of the Dart programming language

  2. Familiarity with Object-Oriented Programming (OOP) concepts, particularly classes and constructors

  3. Basic knowledge of Flutter development (helpful but not required)

  4. Understanding of static variables and methods in Dart

  5. Familiarity with the concept of class instantiation

What is the Singleton Pattern?

The Singleton pattern is a creational design pattern that ensures a class has only one instance and that there is a global point of access to the instance.

Again, this is especially powerful when managing shared resources across an application.

When to Use the Singleton Pattern

You should use a Singleton when you are designing parts of your system that must exist once, such as:

  1. Global app state (user session, auth token, app config)

  2. Shared services (logger, API client, database connection)

  3. Resource heavy logic (encryption handlers, ML models, cache manager)

  4. Application boot security (run platform-specific root/jailbreak checks)

For example, in a Flutter app, Android may check developer mode or root status, while iOS checks jailbroken device state. A Singleton security class is a perfect way to enforce that these checks run once globally during app startup.

How to Create a Singleton Class

We have two major ways of creating a singleton class:

  1. Eager Instantiation

  2. Lazy Instantiation

Eager Singleton

This is where the Singleton is created at load time, whether it's used or not.

In this case, the instance of the singleton class as well as any initialization logic runs at load time, regardless of when this class is actually needed or used. Here's how it works:

class EagerSingleton {
  EagerSingleton._internal();
  static final EagerSingleton _instance = EagerSingleton._internal();

  static EagerSingleton get instance => _instance;

  void sayHello() => print("Hello from Eager Singleton");
}

//usage
void main() {
  // Accessing the singleton globally
  EagerSingleton.instance.sayHello();
}

How the Eager Singleton Works

Let's break down what's happening in this implementation:

First, EagerSingleton._internal() is a private named constructor (notice the underscore prefix). This prevents external code from creating new instances using EagerSingleton(). The only way to get an instance is through the controlled mechanism we're about to define.

Next, static final EagerSingleton _instance = EagerSingleton._internal(); is the key line. This creates the single instance immediately when the class is first loaded into memory. Because it's static final, it belongs to the class itself (not any particular instance) and can only be assigned once. The instance is created right here, at declaration time.

The static EagerSingleton get instance => _instance; getter provides global access to that single instance. Whenever you call EagerSingleton.instance anywhere in your code, you're getting the exact same object that was created when the class loaded.

Finally, sayHello() is just a regular method to demonstrate that the singleton works. You could replace this with any business logic your singleton needs to perform.

When you run the code in main(), the class loads, the instance is created immediately, and EagerSingleton.instance.sayHello() accesses that pre-created instance to call the method.

Pros:

  1. This is simple and thread safe, meaning it's not affected by concurrency, especially when your app runs on multithreads.

  2. It's ideal if the instance is lightweight and may be accessed frequently.

Cons:

  1. If this instance is never used through the runtime, it results in wasted memory and could impact application performance.

Lazy Singleton

In this case, the singleton instance is only created when the class is called or needed in runtime. Here, a trigger needs to happen before the instance is created. Let's see an example:

class LazySingleton {
  LazySingleton._internal(); 
  static LazySingleton? _instance;

  static LazySingleton get instance {
    _instance ??= LazySingleton._internal();
    return _instance!;
  }

  void sayHello() => print("Hello from LazySingleton");
}

//usage 
void main() {
  // Accessing the singleton globally
  LazySingleton.instance.sayHello();
}

How the Lazy Singleton Works

The lazy implementation differs from eager in one crucial way: timing.

Again, LazySingleton._internal() is a private constructor that prevents external instantiation.

But notice that static LazySingleton? _instance; is declared as nullable and not initialized. Unlike the eager version, no instance is created at load time. The variable simply exists as null until it's needed.

The magic happens in the getter: _instance ??= LazySingleton._internal(); uses Dart's null-aware assignment operator. This line says "if _instance is null, create a new instance and assign it. Otherwise, keep the existing one." This is the lazy initialization: the instance is only created the first time someone accesses it.

The first time you call LazySingleton.instance, _instance is null, so a new instance is created. Every subsequent call finds that _instance already exists, so it just returns that same instance.

The return _instance!; uses the null assertion operator because we know _instance will never be null at this point (we just ensured it's not null in the previous line).

This approach saves memory because if you never call LazySingleton.instance in your app, the instance never gets created.

Pros:

  1. Saves application memory, as it only creates what is needed in runtime.

  2. Avoids memory leaks.

  3. Is ideal for resource heavy objects while considering application performance.

Cons:

  1. Could be difficult to manage in multithreaded environments, as you have to ensure thread safety while following this pattern.

Choosing Between Eager and Lazy

Now that we've broken down these two major types of singleton instantiation, it's worthy of note that you'll need to be intentional while deciding whether to create a singleton the eager or lazy way. Your use case/context should help you determine what singleton pattern you need to apply during object creation.

As an engineer, you need to ask yourself these questions when using a singleton for object creation:

  1. Do I need this class instantiated when the app loads?

  2. Based on the user journey, will this class always be needed during every session?

  3. Can a user journey be completed without needing to call any logic in this class?

These three questions will determine what pattern (eager or lazy) you should use to fulfill best practices while maintaining scalability and high performance in your application.

Factory Constructors in the Singleton Pattern

Applying factory constructors in the Singleton pattern can be powerful if you use them properly. But first, let's understand what factory constructors are.

What Are Factory Constructors?

A factory constructor in Dart is a special type of constructor that doesn't always create a new instance of its class. Unlike regular constructors that must return a new instance, factory constructors can:

  1. Return an existing instance (perfect for singletons)

  2. Return a subclass instance

  3. Apply logic before deciding what to return

  4. Perform validation or initialization before returning an object

The factory keyword tells Dart that this constructor has the flexibility to return any instance of the class (or its subtypes), not necessarily a fresh one.

Implementing Singleton with Factory Constructor

This allows you to apply initialization logic while your class instance is being created before returning the instance.

class FactoryLazySingleton {
  FactoryLazySingleton._internal();
  static final FactoryLazySingleton _instance = FactoryLazySingleton._internal();

  static FactoryLazySingleton get instance => _instance;

  factory FactoryLazySingleton() {
    // Your logic runs here
    print("Factory constructor called");
    return _instance;
  }
}

How the Factory Constructor Singleton Works

This implementation combines aspects of both eager and lazy patterns with additional control.

The FactoryLazySingleton._internal() private constructor and static final _instance create an eager singleton. The instance is created immediately when the class loads.

The static get instance provides the traditional singleton access pattern we've seen before.

But the interesting part is the factory FactoryLazySingleton() constructor. This is a public constructor that looks like a normal constructor call, but behaves differently. When you call FactoryLazySingleton(), instead of creating a new instance, it runs whatever logic you've placed inside (in this case, a print statement), then returns the existing _instance.

This pattern is powerful because:

  1. You can log when someone tries to create an instance

  2. You can validate conditions before returning the instance

  3. You can apply configuration based on parameters passed to the factory

  4. You can choose to return different singleton instances based on conditions

For example, you might have different configuration singletons for development vs production:

factory FactoryLazySingleton({bool isProduction = false}) {
  if (isProduction) {
    // Apply production configuration
    _instance.configure(productionSettings);
  } else {
    // Apply development configuration
    _instance.configure(devSettings);
  }
  return _instance;
}

Pros

  1. You can add logic before returning an instance

  2. You can cache or reuse the same object

  3. You can dynamically return a subtype if needed

  4. You avoid unnecessary instantiation

  5. You can inject configuration or environment logic

Cons

  1. Adds slight complexity compared to simple getter access

  2. The factory constructor syntax might confuse developers unfamiliar with the pattern

  3. If overused with complex logic, it can make debugging harder

  4. Can create misleading code where FactoryLazySingleton() looks like it creates a new instance but doesn't

When Not to Use a Singleton

While singletons are powerful, they're not always the right solution. Understanding when to avoid them is just as important as knowing when to use them.

Why Singletons Can Be Problematic

Singletons create global state, which can make your application harder to reason about and test. They introduce tight coupling between components that shouldn't necessarily know about each other, and they can make it difficult to isolate components for unit testing.

Scenarios Where You Should Avoid Singletons

Avoid using the Singleton pattern if:

You need multiple independent instances

If different parts of your app need their own separate configurations or states, singletons force you into a one-size-fits-all approach.

For example, if you're building a multi-tenant application where each tenant needs isolated data, a singleton would cause data to bleed between tenants.

Alternative: Use dependency injection to pass different instances to different parts of your app. Each component receives the specific instance it needs through its constructor or a service locator.

// Instead of singleton
class UserRepository {
  final DatabaseConnection db;
  UserRepository(this.db); 
}

// Usage
final dbForTenantA = DatabaseConnection(tenantId: 'A');
final dbForTenantB = DatabaseConnection(tenantId: 'B');
final repoA = UserRepository(dbForTenantA);
final repoB = UserRepository(dbForTenantB);

Your architecture avoids shared global state

Modern architectural patterns like BLoC, Provider, or Riverpod in Flutter specifically aim to avoid global mutable state. Singletons work against these patterns by reintroducing global state.

Alternative: Use state management solutions designed for Flutter. Provider, Riverpod, BLoC, or GetX offer better ways to share data across your app while maintaining testability and avoiding tight coupling.

// Using Provider instead of singleton
class AppConfig {
  final String apiUrl;
  AppConfig(this.apiUrl);
}

// Provide it at the top level
void main() {
  runApp(
    Provider<AppConfig>(
      create: (_) => AppConfig('https://api.example.com'),
      child: MyApp(),
    ),
  );
}

// Access it anywhere in the widget tree
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final config = Provider.of<AppConfig>(context);

  }
}

It forces tight coupling between unrelated classes

When multiple unrelated classes depend on the same singleton, they become indirectly coupled. Changes to the singleton affect all these classes, making the codebase fragile and hard to refactor.

Alternative: Use interfaces and dependency injection. Define what behavior you need through an interface, then inject implementations. This way, classes depend on abstractions, not concrete singletons.

// Define an interface
abstract class Logger {
  void log(String message);
}

// Implementation
class ConsoleLogger implements Logger {
  @override
  void log(String message) => print(message);
}

// Classes depend on the interface, not a singleton
class PaymentService {
  final Logger logger;
  PaymentService(this.logger);

  void processPayment() {
    logger.log('Processing payment');
  }
}

// Easy to test with mock
class MockLogger implements Logger {
  List<String> logs = [];
  @override
  void log(String message) => logs.add(message);
}

You need clean, isolated testing

Singletons maintain state between tests, causing test pollution where one test affects another. This makes tests unreliable and order-dependent.

Alternative: Use dependency injection and create fresh instances for each test. Most testing frameworks support this pattern, allowing you to inject mocks or fakes easily.

// Testable code
class OrderService {
  final PaymentProcessor processor;
  OrderService(this.processor);
}

// In tests
void main() {
  test('processes order successfully', () {
    final mockProcessor = MockPaymentProcessor();
    final service = OrderService(mockProcessor); 

  });
}

General Guidelines

Use singletons sparingly and only when you truly need exactly one instance of something for the entire application lifecycle. Good candidates include logging systems, application-level configuration, and hardware interface managers.

For most other cases, prefer dependency injection, state management solutions, or simply passing instances where needed. These approaches make your code more flexible, testable, and maintainable.

Conclusion

The Singleton pattern is a powerful creational tool, but like every tool, you should use it strategically.

Overusing singletons can make apps tightly coupled, hard to test, and less maintainable.

But when used correctly, the Singleton pattern helps you save memory, enforce consistency, and control object lifecycle beautifully.

The key is understanding your specific use case and choosing the right implementation approach – whether eager, lazy, or factory-based – that best serves your application's needs while maintaining clean, testable code.

]]> <![CDATA[ System Architecture Documentation Best Practices and Tools ]]> https://www.freecodecamp.org/news/system-architecture-documentation-best-practices-and-tools/ 691484910576aea108fc08d8 Wed, 12 Nov 2025 12:58:57 +0000 Imagine being asked to give UX feedback on a system workflow document and realizing you can’t understand a word of it. That’s exactly what happened to me.

As an IT support officer, I can put myself in the perspective of a user and identify friction points, but this document had no visuals, no simplified explanations, just walls of backend jargon: service mesh, container orchestration, async queues, REST APIs… you name it.

I realized quickly: if someone like me struggles to understand this, so will PMs, frontend devs, new hires, and even other IT staff.

Here’s a practical guide for creating system architecture documentation that anyone on your team can read and use:

Step 1: Show the System from Different Angles

A good architecture doc isn’t just a list of tech terms. Think about who is reading it:

A. Conceptual View (PM/UX/business folks)

  • What the system does for the user.

  • Example: “User Authentication System,” “Checkout Service”

  • Focus on user value and business goals.

B. Component View (frontend developers/IT staff)

  • How the parts interact.

  • Example: “Web App calls API Gateway → Microservice → Database”

  • Focus on data flow and system boundaries.

C. Operational View (backend/DevOps)

  • Where the system runs and how.

  • Example: servers, databases, cloud setup, scaling.

  • Focus on infrastructure and deployment.

This way, everyone can find what’s relevant to their role without getting lost in technical weeds.

Step 2: Make Diagrams the Star

Words alone don’t cut it. Diagrams help people visualize the system, especially if they’re not experts.

Types of Diagrams to Include

  • System Context Diagram: Shows the system and its external dependencies. UX/PM/IT staff can see how it touches users and other systems.

  • Container Diagram: Shows main boundaries like “Web App,” “Auth API,” “Database.” Frontend and backend teams benefit.

  • UML/Component Diagram: Shows internal structure or interactions. Mostly backend focus, but helps everyone understand flow.

Tip: Even a simple flowchart drawn in PowerPoint, Figma, or by hand is better than none. Clarity matters more than perfection.

Diagrams help:

  • UX sees user impact.

  • Frontend knows which services to hook up.

  • Backend sees infrastructure and interactions.

  • Everyone shares the same mental picture.

Example 1: System Context Diagram

Flowchart illustrating an end user visiting a web app, which processes payments via Stripe API and sends emails through SendGrid using webhooks.

This diagram illustrates who uses the system (a person on the web) and which external services it depends on, like Stripe for payments and SendGrid for emails. It doesn't show the internal workings of the system, just what it connects to.

Example 2: Container Diagram

Flowchart depicting a web application architecture. The sequence starts with a web browser, leading to a frontend app, then to an API gateway. The gateway splits into two paths: one leads to an Auth Service connected to a User Database, and the other to an Order Service connected to an Orders Database.

This diagram illustrates the main components of the system: the Web App, which is the user interface; the Auth API, responsible for handling login and security; and the User Database, where user profiles are stored. The arrows indicate how these components interact with each other.

Practical Tip: Tools to Create Clear Architecture Docs.

Step 3: Translate Tech Into User-Relevant Outcomes

System architecture goes beyond databases and queues, focusing on making the product fast, reliable, and secure for users. Link technical requirements to outcomes everyone can understand:

Requirement❌ Technical Jargon✅ User Outcome
ScalabilityKubernetes for container orchestrationCan handle 10x daily users without slowdowns.
PerformanceCDN + cachingPages load in under 500ms, no “loading” screens.
SecurityTLS 1.3 for data transferUser data is safe; only authorized systems access PII(Personally Identifiable Information).

Even a person with basic UX awareness can see why tech decisions matter.

Step 4: Make Communication Clear

One major source of confusion is how different parts of the system talk to each other. Spell it out:

a) Frontend ↔ Backend: Clearly explain how your frontend connects to the backend.

Example: “The website sends login requests to the Auth API.”

b) Backend ↔ Backend: Explain whether services communicate with each other instantly (synchronous) or through background tasks like message queues (asynchronous). This helps the team understand why some actions feel instant to users, while others take time.

Even non-backend readers can follow the flow and understand how it impacts the product.

Step 5: Keep it Simple and Consistent

  • Use headings, bullet points, and a table of contents. Don’t write a novel.

  • Keep names consistent: “User Service” in diagrams should match text labels.

  • Explain the “why” behind major decisions:

“We chose a NoSQL DB for User Profiles because it requires fast read/write for non-relational data.”

Consistency and simplicity make the doc useful to everyone, not just backend experts.

System Architecture Documentation Tools for Teams

Great architecture documentation lives where your team already works and uses tools that are easy to update, share, and understand. Below are the common types of tools teams use, grouped by purpose.

Documentation Platforms (Where You Write the Full Doc)

You can use these tools to combine text, diagrams, and structure a document.

Google Docs
Simple, familiar, and collaborative. Supports real-time comments, edit history, and easy sharing. Perfect if your team already uses Gmail or Drive. Just paste diagrams as images.

Confluence
Common in larger companies. Integrates with Jira, supports page templates, and lets you embed diagrams. Good for structured knowledge bases.

Notion
Flexible workspace for small teams. Mix docs, tasks, and diagrams in one place. Great if your team uses Notion for other work.

GitHub/GitLab Wikis (with Markdown)
Ideal for engineering-heavy teams. Docs live next to your code, and you can include diagrams using simple code (like Mermaid). Changes are tracked like code.

Start with Google Docs if you’re unsure. A living doc people actually read is better than a “perfect” one no one opens.

Diagramming Tools (Where You Create Visuals)

These help you draw the architecture diagrams you’ll add to your documentation platform.

Draw.io
Free, browser-based, and drag-and-drop simple. No sign-up needed. Exports clean PNG/SVG files you can paste into Docs or Confluence. Great for C4-style diagrams (System Context, Container, and so on).

Figma
If your team already uses Figma for design, you can create architecture diagrams using basic shapes and arrows. Real-time commenting makes feedback easy. Just export as PNG for Docs.

Mermaid (Diagrams as Code)
Write simple text like User --> Web App, and it becomes a diagram. Works in GitHub, GitLab, and tools like Obsidian. Use the Mermaid Live Editor to design, then download and paste into Google Docs.

A Key Insight from Practicing Architects.

Avoid tools that only produce static images (like PowerPoint, Canva, or basic whiteboards) for anything beyond quick sketches. If the same service appears in three diagrams and you rename it, you’ll have to update all three manually, leading to outdated and inconsistent docs.

How They Work Together

  1. Write your doc in Google Docs (or your team’s existing platform).

  2. Create diagrams in Draw.io or Figma (or try Mermaid if you’re curious).

  3. Paste the diagram into your doc, add alt text, and explain what it shows in plain language.

This combo gives you accessibility, collaboration, and maintainability without overwhelming you or your team.

Conclusion

You don’t need to be a senior engineer to write great architecture docs. You just need clarity, empathy, and the willingness to explain “why.”

]]>