DEV Community: Derrick Odhiambo

Retrofitting Clean Architecture onto a Next.js App Without Stopping the World

Derrick Odhiambo — Thu, 22 Oct 2026 07:45:59 +0000

How I took a frontend that grew without a plan, measured the mess, and moved
it to clean architecture in eleven small PRs, finding real bugs along the way.

When I started building our markets-data platform, I didn't think about architecture. I focused on getting equities, indices, and screen prices.
It's a Next.js App Router project that shows stock exchange data, news, watchlists, and paid subscriptions.

That worked until it didn't. As the app grew, I adopted clean architecture for new features: entities in a domain layer, use cases in an application layer, repositories in infrastructure. The older code kept doing what it had always done. Server actions inside route folders called the backend with axios. Business logic lived in app/(subscription)/lib.
There were two places for shared components, two for hooks, and four for a utility function.

I ended up with a hybrid. Worse, even the "clean" parts leaked: the domain imported types from the application layer, and use cases were typed against
concrete API classes rather than interfaces.

Here is how I fixed it without a rewrite or freezing feature work.

Why bother with clean architecture in a frontend?

The core idea fits in one sentence: source code dependencies only point
inwards.

UI (routes, components, server actions)
  → presentation (mappers, formatters)
  → application (use cases)
  → domain (entities, repository interfaces)

Infrastructure (HTTP clients, repositories, config) sits on the side,
implementing interfaces the domain defines.

The domain doesn't know React exists. A use case doesn't know whether its repository calls a REST API, reads localStorage or is a test fake. A component doesn't know which endpoint its data came from.

That pays off in three practical ways:

Backend churn stops at one file. When the API renames a field, the DTO that maps the response changes and nothing else does.
Logic is testable without mocking the world. A use case test needs a three-line fake, not an HTTP mock.
Details are swappable. I moved "recently viewed instruments" from an API to localStorage by writing one new repository. The use case and UI didn't change.

Step 1: Measure before you move anything

The temptation with a messy codebase is to start moving files. I started with an audit instead, sorting every problem I could find into six buckets:

Dependency-rule violations inside the "clean" layers
Duplicated core concepts (two APIError classes, two use case styles)
Data access that bypassed the architecture entirely
Business logic living in the routing layer
Dead code
Folder sprawl

Then, before touching any of it, I encoded the architecture as lint
rules. eslint-config-next already ships eslint-plugin-import, whose import/no-restricted-paths rule checks resolved paths. It catches @/infrastructure/... and ../../../infrastructure/... alike.

const coreZones = [
  {
    target: "./src/domain",
    from: ["./src/application", "./src/infrastructure", "./src/presentation", ...UI],
    message: "Domain must not depend on other layers.",
  },
  {
    target: "./src/application",
    from: ["./src/infrastructure", "./src/presentation", ...UI],
    message: "Depend on a domain interface, not an implementation.",
  },
  // …presentation, infrastructure, shared, and "src/app is for routes only"
];

Every rule's message tells the developer how to fix the problem, not just that one exists.

The first run produced 120 boundary violations. That number became the most useful thing in the whole project. "The codebase is messy" is an opinion; "120 violations, down to 82 this week" is progress you can see.

Side quest: on Next.js 16, next lint no longer exists, and my old
FlatCompat-based config crashed with "Converting circular structure to
JSON". Switching to the native flat configs that eslint-config-next now
ships fixed it. Lint had been quietly not running.

Step 2: Warnings now, errors later

If I'd introduced those rules as errors, every PR in the repo would have failed on day one. So they started as warnings.

The trick is the second half: when a layer reaches zero violations, its rules become errors in the same PR.

{
  // Core layers and shared code are clean, so new violations there fail lint
  files: ["src/domain/**", "src/application/**", "src/presentation/**",
          "src/infrastructure/**", "src/shared/**"],
  rules: { "import/no-restricted-paths": ["error", { zones: coreZones }] },
}

Each cleaned-up layer stayed clean. Progress couldn't slide back quietly.

Step 3: Fix the core first

I started in the middle, with domain and application, because everything else depends on them.

The most instructive bug was the simplest. There were two identical
APIError classes, one in the domain and one in infrastructure. They had the same code, line for line. But an error thrown by a repository using one class failed instanceof against the other, and the user saw "An unknown error occurred" instead of the real message. Duplicated core types aren't just untidy. They break things in ways that are hard to trace.

The rest of the phase was mostly moving things to where they belonged:

Raw API response shapes (snake_case, wrapped in { success, data, error }) moved from the application layer to infrastructure. The domain stopped importing them.
Domain enums moved out of infrastructure/types/enums into the domain.
Use cases were retyped against domain interfaces instead of concrete *RepositoryApi classes.
Formatters, which decide how a price or date is displayed, moved from infrastructure into presentation.

Step 4: Give the wiring a home

Once use cases depended on interfaces, something had to create the concrete classes and pass them in. Before, sixteen server action files each did it themselves, every one with its own copy of the same error-handling lambda.

I replaced that with a composition root: one file that creates every repository and use case.

// src/infrastructure/di/server.ts
import "server-only";

export function toUserError(error: unknown) {
  if (error instanceof APIError) {
    return { message: error.getUserFriendlyMessage(), statusCode: error.getStatusCode() };
  }
  return { message: "An unknown error occured", statusCode: 500 };
}

export const currencyUseCase = new CurrencyUseCase(new CurrencyRepositoryApi());
export const equityUseCase = new EquityUseCase(
  new EquityRepositoryApi(),
  new SystemDateProvider(),
  toUserError,
);

Server actions shrank to almost nothing:

"use server";
import { currencyUseCase } from "@/infrastructure/di/server";

export async function getPairConversion(base: string, target: string, amount: number) {
  return currencyUseCase.convert(base, target, amount);
}

The import "server-only" line matters. These repositories send an API key and the user's auth cookie. If a client component ever imports the container, the build fails.

The day the plan was wrong

My plan said to route geolocation through a server action like everything else. Fortunately, I stopped to check what the location API actually does.

It works out the country from the IP address of whoever calls it. From the server, every visitor would have been located at our server, and shown that region's subscription prices and payment methods.

So there's a second, deliberately small container for things that must
run in the browser:

// src/infrastructure/di/client.ts
// Runs in the browser so the lookup sees the visitor's IP
export const geolocationUseCase = new GeolocationUseCase(new GeolocationRepositoryApi());

The layers didn't change. Only where the code runs did. Clean architecture told me where the code belongs, but not where it executes. That still takes thought.

Step 5: Migrate one slice at a time

The legacy areas moved one product area per PR: auth, subscriptions and payments, currencies, news, geolocation. Each one was tested by hand where possible and with unit tests where not.

My favourite example is the news feed. The old flow was:

The browser fetched our own /feed.xml route.
That route downloaded the publisher's RSS, parsed it… and turned it back into XML.
The browser then parsed that XML a second time with rss-parser.

After the migration, an RssFeedRepositoryApi parses each feed once, on the server. The browser gets plain article objects from a server action, and rss-parser dropped out of the client bundle. /feed.xml still exists for RSS readers, built from the same use case.

The part that took discipline was keeping the output identical. The home page displays the raw pubDate string, so the new mapper reproduces the old format exactly (toUTCString()). Users shouldn't notice an architecture change.

Step 6: Consolidate, and audit what reaches the browser

The last phase merged the leftover folders (components, hooks, lib, utils, types) into shared or the feature that owned them. Two rules decided where things went:

Shared code may not depend on features. The navbar needs auth and subscription state, so it went to features/navigation, not shared.
Look-alikes aren't duplicates until proven identical. Two DatePickers and two useFilters hooks turned out to differ in styling, page size, and default values. Merging them would have changed behaviour for one set of users. They kept separate, clearly named homes.

That phase also caught the most important bug of the project.

In Next.js, a NEXT_PUBLIC_* variable is inlined into any browser bundle whose code references it. Our config module referenced some sensitive values under that prefix, and because browser code imported the config, those values ended up in client JavaScript. That was true even though no browser code used those particular fields.

The fix was structural, not a one-off:

a small shared/config/public.ts with only the values a visitor may see
the full config marked server-only, so the mistake can't come back quietly
a check after each build: search .next/static for the secret values (not their names), and expect zero matches

Moving code is not the same as preserving behaviour

If I had to pick one lesson, it's this one. Several "obvious" changes turned out to be wrong when I actually checked:

Geolocation on the server would have shown everyone the wrong prices.
Merging the look-alike components would have changed table sizes and defaults.
"Fixing" an RSS image bug could have crashed news pages. The parser renamed media:content before the code looked for it, so those images were never used. But next/image only allowed one image host, so picking up more image URLs could have introduced hosts it rejects. I checked the live feeds first, then made the fix to filter images through the same host allowlist next.config.ts uses.

Architecture work finds bugs

Pushing code through proper layers forces you to read it. Along the way, I found:

a reset-password action that never awaited its request, so it always said "success"
a "Try again" button that called router.refresh(), which never retries a failed client-side React Query request
the image lookup that could never match
sensitive config inlined into the browser bundle

None of these came up in normal feature work. They all came up because a refactor made someone look closely at the code.

Untestable by hand? Then test it properly

Some flows were hard to exercise manually: coupons need a valid code, live price highlighting needs the market open, error states need an API to fail.
Rather than mark them "tested", I covered them with unit tests. Because each use case depends on an interface, the fakes are trivial:

const useCaseWith = (convert: ICurrencyRepository["convert"]) =>
  new CurrencyUseCase({ convert });

it("rejects missing input without calling the API", async () => {
  const convert = jest.fn();
  const result = await useCaseWith(convert).convert("", "KES", 2);

  expect(convert).not.toHaveBeenCalled();
  expect(result.error?.errorType).toBe("invalid-input");
});

For the important ones, I also ran a quick mutation check: break the code on purpose, confirm the test fails, then restore it. A test that can't fail is worse than no test, because it gives you confidence you haven't earned.

Know when not to add a layer

Not everything got the full treatment. The auth API routes forward
credentials and cookies to the backend and holds no business rules, so they call an AuthGatewayApi directly, with no use case in between. A use case there would only pass values through.

The same goes for the old local login and profile pages. Authentication now happens entirely through SSO, but I kept those pages as a fallback in case we ever need to revert. They're documented as a deliberate exception and still show up in lint, so they stay in view.

Clean architecture is a means to an end, not a checklist.

The results

	Before	After
Layer-boundary violations	120	4 (all deliberate)
Layers where a violation fails lint	none	5
Lint warnings	134	17 (0 errors)
Tests	40	77
Top-level `src` folders	13	8
Places that build use cases	18	2
Sensitive values in the browser bundle	some	none, with a build-time guard

Eleven PRs, each one reviewable and shippable on its own, with no feature freeze.

If you're about to do the same

Audit, then encode the rules in lint before moving code. You need a number.
Start with warnings, and turn each clean layer's rules into errors.
Fix the core first. Everything else depends on it.
Give your wiring one home, and make it server-only if it holds anything sensitive.
Migrate one slice per PR, and keep the output identical.
Check behaviour, not just structure. Look-alikes, "obvious" moves and bug fixes all deserve a second look.
Test what you can't click through, and prove the tests can fail.
Write down your exceptions. A documented shortcut is a decision; an undocumented one is debt.

The codebase isn't perfect. But it now has a shape that explains itself, and lint enforces that shape.

map() method under the hood

Derrick Odhiambo — Wed, 09 Sep 2026 13:39:39 +0000

map() is an array method that creates a new array populated with the results of calling a provided function on every element in the calling array.

// `thisArg` is optional; when specified, it provides a value for 
// `this` when `callbackFn` is executing
map(callbackFn, thisArg)

map() preserves the same index range and transforms only existing values. The output has the same length and the same holes as the input, but the callback result replaces each existing element.

Array.prototype.myMap = function (callbackFn, thisArg) {
  // We use this to determine how many indexes we need to inspect.
  const len = this.length;

  // This is important because map() always returns a new array.
  // Using new Array(len) also preserves holes in sparse arrays.
  const array = new Array(len);

  // We check every index because the original array may contain holes.
  for (let k = 0; k < len; k++) {
    // A sparse array can have a missing index (a "hole").
    // `k in this` allows us to skip those holes instead of calling
    // the callback with undefined.
    if (k in this) {

      // this[k]   → current element
      // k         → current index
      // this      → original array
      // callbackFn.call(thisArg, ...) allows the caller to control
      // what `this` refers to inside the callback.
      // The value returned by the callback is stored at the same
      // index in the new array.
      array[k] = callbackFn.call(
        thisArg,
        this[k],
        k,
        this
      );
    }
  }

  return array;
};

For the spec solution, a specification-oriented version based on Array.prototype.map looks like this.

Array.prototype.myMap = function (callbackFn, thisArg) {
  // This allows myMap to work with array-like objects and handles
  // primitive values consistently with the specification.
  const O = Object(this);

  // `>>> 0` converts the length into an unsigned 32-bit integer,
  // giving us the number of indexes we need to process.
  const len = O.length >>> 0;

  // Native map() throws a TypeError when the callback is not a function.
  if (typeof callbackFn !== "function") {
    throw new TypeError("this is not a function");
  }

  // map() does not modify the original array.
  // Creating the array with `len` also preserves holes in sparse arrays.
  let array = new Array(len);

  let k = 0;

  while (k < len) {

    // Object properties are ultimately accessed using property keys,
    // which are strings (or symbols).
    let presentKey = String(k);

    // This is important for sparse arrays.
    // A hole means the property does not exist, so map() skips it.
    // `in` also checks the prototype chain, which matches the
    // specification's HasProperty operation.
    if (k in O) {
      let kValue = O[k];

      //     - kValue → current element
      //     - k      → current index
      //     - O      → original array/object
      // `call()` allows us to provide the `thisArg` as the `this`
      // value inside the callback.
      let mappedValue = callbackFn.call(
        thisArg,
        kValue,
        k,
        O
      );

      // Instead of simply doing:
      //     array[k] = mappedValue;
      // the specification uses CreateDataProperty, which is
      // conceptually represented here using Object.defineProperty().
      // This explicitly creates an ordinary data property with:
      // value        → the value returned by the callback
      // writable     → the property can be changed later
      // enumerable   → the property appears during enumeration
      // configurable → the property can be deleted or reconfigured
      // Most importantly, we only create this property when `k in O`
      // is true. If the original array has a hole at this index,
      // this block is never executed, so the result keeps the hole.
      Object.defineProperty(array, presentKey, {
        value: mappedValue,
        writable: true,
        enumerable: true,
        configurable: true,
      });
    }
    k = k + 1;
  }
  return array;
};

How reduce() works under the hood

Derrick Odhiambo — Mon, 07 Sep 2026 09:16:34 +0000

reduce() is an Array method that executes a reducer callback on each element in order and returns a single value.

reducer(callbackFn);
reducer(callbackFn, initialValue);

const array = [1, 2, 3, 4];

// Example: 0 + 1 + 2 + 3 + 4
const initialValue = 0;

const sumWithInitial = array.reduce(
  (accumulator, currentValue) => accumulator + currentValue,
  initialValue,
);

console.log(sumWithInitial);
// Expected output: 10

reduce() calls your function with (accumulator, currentValue, currentIndex, array) on every element. If you don't pass an initialValue, the array's first element becomes the starting accumulator, and the loop begins from index 1 instead of 0 — otherwise, it starts from initialValue at index 0.

On the first call, there's no previous result to build on yet, so accumulator starts as whatever you provided as initialValue (or the array's first element, if you didn't), and callbackFn combines that starting value with currentValue to produce the first real result.

What actually happens under the hood

There are many ways to implement a reduce method, but we'll use the ECMAScript specification as our guide. It breaks the behavior of reduce down into clear, well-defined steps, giving us a solid foundation for implementing it ourselves.

First, a few edge cases worth knowing.

An empty array, with or without the initialValue argument.
A single-value array, with and without the initialValue argument.
Sparse arrays with interior holes, e.g. [ , , , 2, 3]. Empty slots are skipped while traversing.
Sparse arrays with no initialValue.
All-hole array with no initialValue, e.g., [ , , , ].
Index properties inherited through the array's prototype.
undefined passed explicitly as an initialValue

This was my initial attempt using a for loop:

Array.prototype.myReducer = function (callbackFn, initialValue) {
 const len = this.length;
 const noInitialValue = arguments.length <= 1;

 if (typeof callbackFn !== "function") {
  throw new TypeError("This is not a function");
 }

 let startingIndex = 0;
 let acc = undefined;

 if (!noInitialValue) {
  acc = initialValue;
 } else {
  let indexFound = false;

  for (let k = 0; k < len; k++) {
   if (k in this) {
    acc = this[k];
    indexFound = true;
    startingIndex = k + 1;
    break;
   }
  }
  if (indexFound === false) {
   throw new TypeError("Empty array with no initial value");
  }
 }
 for (let k = startingIndex; k < len; k++) {
  if (k in this) {
   acc = callbackFn(acc, this[k], k, this);
  }
 }
 return acc;
}

Now the spec implementation following the ECMAScript implementation guide:

Array.prototype.myReducer = function (callbackFn, initialValue) {
  // Reduce requires a real function to call on each element — reject
  // anything else immediately, before doing any work on the array.
  if (typeof callbackFn !== "function") {
    throw new TypeError("This is not a function");
  }

  // Object(this) guarantees O is always a proper object to operate on,
  // even in edge cases where `this` isn't already a genuine array —
  // this is what lets myReducer be "borrowed" and called on array-like
  // objects (e.g. via Array.prototype.myReducer.call(arrayLike, fn)).
  const O = Object(this);

  // `>>> 0` coerces O.length into a sane, non-negative 32-bit unsigned
  // integer, so the loop below always has a safe bound to run against,
  // even if O.length is missing, negative, or not a number at all.
  const len = O.length >>> 0;

  // arguments.length, not initialValue itself, is what tells us whether
  // a second argument was passed. Checking `initialValue !== undefined`
  // instead would incorrectly treat myReduce(fn, undefined) — a
  // deliberate, if unusual, call — as if no initial value were given.
  const noInitialValue = arguments.length < 2;

  // Reducing an empty array with nothing to start from is genuinely
  // undefined behaviour — there's no way to produce a meaningful result,
  // so this matches native reduce() in throwing rather than guessing.
  if (len === 0 && noInitialValue) {
    throw new TypeError("Reduce of empty array with no initial value");
  }

  let k = 0; // current index into the source array
  let accumulator = undefined;

  if (!noInitialValue) {
    // An initial value was supplied — use it as-is, and the main loop
    // below will start from index 0.
    accumulator = initialValue;
  } else {
    // No initial value: the accumulator has to start as the array's
    // first *present* element — not just index 0, since sparse arrays
    // can have holes at the start. We scan forward until we find one.
    let kPresent = false;

    while (kPresent === false && k < len) {
      let propertyKey = String(k);

      // `in` checks whether the property genuinely exists — including
      // via the prototype chain — which correctly distinguishes a real
      // hole (nothing assigned) from an index explicitly set to
      // undefined. A plain O[k] !== undefined check would get this wrong.
      if (propertyKey in O) {
        kPresent = true;
        accumulator = O[k];
      }
      k = k + 1; // advance regardless, whether or not this index was present
    }

    // If we scanned the whole array and never found a present element,
    // every index was a hole — functionally the same as an empty array
    // for reduce's purposes, so the same error applies.
    if (kPresent === false) {
      throw new TypeError("Reduce of empty array with no initial value");
    }
  }

  // Main reduction loop. This runs unconditionally, regardless of which
  // branch above set the accumulator — whether it came from
  // initialValue or from scanning for the first present element, every
  // remaining element still needs to be folded in.
  while (k < len) {
    let propertyKey = String(k);

    // Same hole-check as above: skip indexes that were never assigned,
    // rather than passing `undefined` into the callback for them.
    if (propertyKey in O) {
      let kValue = O[propertyKey];

      // Argument order matters here: (accumulator, currentValue,
      // currentIndex, array) — matching the real callback signature.
      // accumulator is always the FIRST argument; getting this order
      // wrong (e.g., passing kValue first) silently produces incorrect
      // results without throwing any error.
      accumulator = callbackFn(accumulator, kValue, k, O);
    }
    k = k + 1;
  }

  return accumulator;
};

myReduce reproduces the native reduce() with the same argument handling and the same edge cases around missing initial values and sparse arrays.
ECMAScript specification guide

How the filter array method works under the hood

Derrick Odhiambo — Sat, 05 Sep 2026 19:03:55 +0000

Have you ever wondered how the filter() works in JavaScript? I came accross that problem. After a few days of procrastination and fear, and reading the documentation and articles, I can say I finally understood how it works under the hood.

filter() takes an array and a test, a function that returns true or false for each item in the array. It returns a new array with the items that passed the test, leaving the original array unmodified.

Say you've got a list of users and you only want the active ones:

const users = [
  { name: "Amina", active: true },
  { name: "Brian", active: false },
  { name: "Carol", active: true },
];

const activeUsers = users.filter(user => user.active);
// [{ name: "Amina", active: true }, { name: "Carol", active: true }]

And just like magic, it works. You have your active users.

That is the whole mental model: loop, test, keep or skip, return a new array. filter() silently guarantees this until you try to build it yourself.

What happens with sparse arrays? What happens if you pass something that is not a function? What if your callback function relies on this?

My first version worked; it compiled, ran on a plain array, and it gave me exactly what I expected.

Array.prototype.myFilter = function (callbackFn, thisArg) {
 const len = this.length;
 let results = [];
 let k = 0;
 let newIndex = 0;

 for (let k = 0; k < len; k++) {
  if (Object.hasOwn(this, k)) {
   let kValue = this[k];
   const testPassed = callbackFn.call(thisArg, kValue, k, this);

   if (testPassed) {
    results[newIndex] = kValue;
    newIndex = newIndex + 1;
   }
  }
 }
 return results;
}

Where my first attempt fell apart
No guard on the callback. I never checked if callbackFn was actually a plain function. The real filter() fails fast, at the top, with a message that tells you what actually went wrong.

Handling sparse arrays: Object.hasOwn worked, but it wasn't checking the same thing. Object.hasOwn(this, k) checks whether the this object has the k property; the only problem is that hasOwn checks only the object's own properties. It deliberately ignores the prototype chain.

After reading the ECMAScript documentation guide, this is the spec solution for how filter() works under the hood.

Array.prototype.myFilter = function (callbackFn, thisArg) {
  // Check if the callback is a function; if not, throw a TypeError.
  if (typeof callbackFn !== "function") {
    throw new TypeError("This is not a function");
  }

  // This is the backbone of the filter function.
  // 'this' refers to the value that called 'myFilter'.
  // Object(this) ensures 'this' is always treated as an object.
  const O = Object(this);

  // Get the length of the array-like object.
  // The `>>> 0` coercion forces the length into a sane, non-negative
  // 32-bit unsigned integer, even if the real value is malformed.
  const len = O.length >>> 0;

  // Initialize an empty array that values passing the test will be appended to.
  let result = [];

  // Two separate indexes: k tracks position in the original array,
  // N tracks position in the result array. Filter skips holes in sparse
  // arrays, so without two separate counters, the result could end up
  // with gaps instead of being densely packed.
  let k = 0; // current index in the original array
  let N = 0; // next index to write to in the result array

  while (k < len) {
    // Check if a property exists at index k. Using `in` (rather than
    // Object.hasOwn) is deliberate — it also checks the prototype chain,
    // matching the spec's HasProperty behavior exactly.
    if (k in O) {
      let kValue = O[k];

      // Run the test, coercing the result to a real boolean.
      const testPassed = Boolean(callbackFn.call(thisArg, kValue, k, O));

      if (testPassed) {
        result[N] = kValue;
        N++;
      }
    }
    k++; // always advance k, whether or not the value existed or passed
  }

  return result; // the new array containing only the elements that passed the test
};

What surprised me most wasn't any single fix; it was realizing how much invisible, deliberate design sits beneath a method I'd called a thousand times without ever wondering how it worked. Reading the spec isn't about memorizing algorithm steps to recite in an interview. It's about building the reflex to ask "but what if the input isn't clean?" before you ship something and consider it done. That reflex is worth more than any single polyfill you'll ever write.

For an in-depth explanation, please refer to this article by Priya Khanna