DEV Community: Jorge Castillo

Part 4 — Practical Guide: Adding Features & Architectural Rules

Jorge Castillo — Fri, 09 Oct 2026 20:06:30 +0000

Across Parts 1, 2, and 3, we laid down the foundational theory, modular directory layouts, and advanced engineering patterns—such as Dependency Injection with InversifyJS, Composition Roots, and tag-based cache invalidation—that power a scalable frontend application.

Now, we bring everything together into an actionable, real-world development workflow. How does an engineer build a new business feature from scratch without violating architectural boundaries? How do we integrate validation, handle async side effects, and connect UI components? And crucial for scaling teams, how do we automatically enforce these architectural boundaries in CI/CD pipelines so technical debt never creeps back in?

In this final installment of our series, we walk step-by-step through implementing an end-to-end Discount Coupon feature in our reference repository, React-Clean-Architecture, write comprehensive unit and integration test suites, and establish automated static analysis guardrails to protect your domain boundaries.

🏗️ The Feature Workflow: Inward-Outward Development

When adding a new feature to a Clean Architecture application, we execute an Inward-Outward development workflow. We start at the core Domain layer (business logic and invariants) and work our way outward through Application orchestration, Infrastructure implementation, and finally Presentation rendering.

flowchart LR
  Step1\["1. Domain Layer\<br/>(Entities & Value Objects)"] --> Step2\["2. Application Layer\<br/>(Ports & Command Handlers)"]
  Step2 --> Step3\["3. Infrastructure Layer\<br/>(Adapters & IoC Bindings)"]
  Step3 --> Step4\["4. Presentation Layer\<br/>(ViewModel Hook & React Component)"]

By completing inner layers first, we ensure our business rules are fully validated and tested before writing a single line of React or API integration code.

🛠️ Step-by-Step Feature Implementation: Discount Coupons

We will build a feature that allows shoppers to apply a promotional discount coupon code to their active cart.

Step 1: Core Domain Modeling (Value Objects & Entity Invariants)

We start in the pure Domain Layer by creating an immutable CouponCode Value Object and extending our Cart Entity to handle discount rules.

1. The Value Object

The CouponCode encapsulates formatting and validation constraints.

export class CouponCode {
  private constructor(
    readonly value: string,
    readonly discountPercentage: number
  ) {
    if (!value || value.trim().length === 0) {
      throw new Error("Coupon code cannot be empty.");
    }

    if (discountPercentage <= 0 || discountPercentage > 100) {
      throw new Error("Discount percentage must be between 1 and 100.");
    }
  }

  static create(value: string, discountPercentage: number): CouponCode {
    return new CouponCode(value.toUpperCase().trim(), discountPercentage);
  }

  equals(other: CouponCode): boolean {
    return this.value === other.value && this.discountPercentage === other.discountPercentage;
  }
}

2. Domain Entity Mutation & Invariants

Next, we update the Cart entity. Domain entities guarantee that invalid state combinations never exist in memory.

export class Cart {
  private constructor(
    readonly id: string,
    private _items: CartItem[],
    private _appliedCoupon?: CouponCode
  ) {}

  static create(id: string, items: CartItem[] = []): Cart {
    return new Cart(id, items);
  }

  get items(): readonly CartItem[] {
    return [...this._items];
  }

  get appliedCoupon(): CouponCode | undefined {
    return this._appliedCoupon;
  }

  applyCoupon(coupon: CouponCode): void {
    if (this._appliedCoupon && this._appliedCoupon.equals(coupon)) {
      throw new Error("This coupon is already applied to the cart.");
    }

    this._appliedCoupon = coupon;
  }

  removeCoupon(): void {
    this._appliedCoupon = undefined;
  }

  calculateTotal(): Money {
    const subtotal = this._items.reduce(
      (sum, item) => sum.add(item.totalPrice),
      Money.create(0)
    );

    if (!this._appliedCoupon) {
      return subtotal;
    }

    const discountMultiplier = (100 - this._appliedCoupon.discountPercentage) / 100;
    const discountedAmount = subtotal.amount * discountMultiplier;

    return Money.create(discountedAmount, subtotal.currency);
  }
}

Step 2: Application Layer (Ports & Use Case Command Handler)

With domain logic secured, we define the application ports and build the ApplyCouponCommandHandler.

1. Defining the Verification Port

The application layer requires a service to verify coupon codes against external rules without knowing how verification is performed.

export interface ICouponVerificationService {
  verify(code: string): Promise<CouponCode>;
}

2. Building the Command Handler

The ApplyCouponCommandHandler orchestrates fetching the cart, verifying the coupon, mutating the entity, persisting changes, and invalidating relevant cache tags.

export interface ApplyCouponInput {
  cartId: string;
  code: string;
}

@injectable()
export class ApplyCouponCommandHandler {
  constructor(
    @inject(TYPES.CARTS_REPOSITORY) private readonly cartRepository: ICartRepository,
    @inject(TYPES.COUPON_SERVICE) private readonly couponService: ICouponVerificationService,
    @inject(TYPES.CACHE) private readonly cacheManager: CacheManager
  ) {}

  async execute(input: ApplyCouponInput): Promise<void> {
    const cart = await this.cartRepository.getById(input.cartId);
    if (!cart) {
      throw new Error(`Cart with ID "${input.cartId}" was not found.`);
    }

    // 1. Verify coupon code via external service port
    const coupon = await this.couponService.verify(input.code);

    // 2. Enforce entity domain rules
    cart.applyCoupon(coupon);

    // 3. Persist updated domain state
    await this.cartRepository.save(cart);

    // 4. Trigger tag-based cache invalidation for reactive UI updates
    this.cacheManager.invalidateTags(["cart", "pricing"]);
  }
}

Step 3: Infrastructure Layer (Adapter & IoC Container Setup)

Now we fulfill the abstract contract by implementing the concrete HTTP adapter and registering bindings in the Composition Root.

1. Concrete REST Adapter

export @injectable()
class ApiCouponVerificationService implements ICouponVerificationService {
  async verify(code: string): Promise<CouponCode> {
    const response = await fetch(`/api/v1/coupons/verify?code=${encodeURIComponent(code)}`);

    if (!response.ok) {
      throw new Error("Invalid or expired discount coupon code.");
    }

    const data = await response.json();
    return CouponCode.create(data.code, data.discount_percentage);
  }
}

2. Registering InversifyJS Symbols & Container Bindings

export const TYPES = {
  // Existing identifiers...
  COUPON_SERVICE: Symbol.for("COUPON_SERVICE"),
  APPLY_COUPON_COMMAND_HANDLER: Symbol.for("APPLY_COUPON_COMMAND_HANDLER"),
};

container.bind<ICouponVerificationService>(TYPES.COUPON_SERVICE).to(ApiCouponVerificationService);
container.bind<ApplyCouponCommandHandler>(TYPES.APPLY_COUPON_COMMAND_HANDLER).to(ApplyCouponCommandHandler);

Step 4: Presentation Layer (Custom Hook & Thin View Component)

Finally, we connect our application layer to React components through a custom ViewModel hook.

1. The Custom ViewModel Hook

export function useApplyCouponViewModel() {
  const handler = useDependency<ApplyCouponCommandHandler>(TYPES.APPLY_COUPON_COMMAND_HANDLER);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const [success, setSuccess] = useState(false);

  const applyCoupon = async (cartId: string, code: string) => {
    setLoading(true);
    setError(null);
    setSuccess(false);

    try {
      await handler.execute({ cartId, code });
      setSuccess(true);
    } catch (err) {
      setError((err as Error).message);
    } finally {
      setLoading(false);
    }
  };

  return { applyCoupon, loading, error, success };
}

2. The React View Component

The UI component contains zero business logic; it merely collects user input and renders state.

export const CouponInputForm: React.FC<{ cartId: string }> = ({ cartId }) => {
  const [code, setCode] = useState("");
  const { applyCoupon, loading, error, success } = useApplyCouponViewModel();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

    if (code.trim()) {
      applyCoupon(cartId, code);
    }
  };

  return (
    <div className="coupon-container">
      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          type="text"
          value={code}
          onChange={(e) => setCode(e.target.value)}
          placeholder="PROMO2026"
          disabled={loading}
          className="border p-2 rounded"
        />
        <button type="submit" disabled={loading || !code.trim()} className="btn-primary">
          {loading ? "Applying..." : "Apply Coupon"}
        </button>
      </form>

      {error && <p className="text-red-500 text-sm mt-1">{error}</p>}
      {success && <p className="text-green-500 text-sm mt-1">Coupon successfully applied!</p>}
    </div>
  );
};

🧪 Comprehensive Feature Verification & Testing

Because we decoupled domain logic and use cases from UI frameworks, we can thoroughly verify this feature using fast unit and integration tests.

1. Domain Unit Test (Zero Mocks)

describe("Cart Entity - Coupon Discount Invariants", () => {
  it("should apply percentage discount correctly to cart total", () => {
    const cart = Cart.create("cart-1");
    const item = CartItem.create("prod-1", Money.create(100, "USD"), 1);
    const coupon = CouponCode.create("SAVE20", 20);

    cart.addItem(item);
    cart.applyCoupon(coupon);

    expect(cart.calculateTotal().amount).toBe(80);
  });

  it("should prevent applying the same coupon code twice", () => {
    const cart = Cart.create("cart-1");
    const coupon = CouponCode.create("SAVE20", 20);

    cart.applyCoupon(coupon);

    expect(() => cart.applyCoupon(coupon)).toThrow("This coupon is already applied to the cart.");
  });
});

2. Application Integration Test (In-Memory Fake)

describe("ApplyCouponCommandHandler", () => {
  it("should process coupon application and invalidate cache tags", async () => {
    const container = createApplicationContainer("test");
    const repo = container.get<ICartRepository>(TYPES.CARTS_REPOSITORY);

    // Seed initial cart
    await repo.save(Cart.create("cart-100"));

    const handler = container.get<ApplyCouponCommandHandler>(TYPES.APPLY_COUPON_COMMAND_HANDLER);

    await handler.execute({ cartId: "cart-100", code: "SAVE20" });

    const updatedCart = await repo.getById("cart-100");
    expect(updatedCart?.appliedCoupon?.value).toBe("SAVE20");
  });
});

🔒 Enforcing Architectural Rules & Automated Guardrails

Documenting architectural guidelines in a README.md is rarely enough. As engineering teams scale, developers working under tight deadlines will accidentally import infrastructure adapters into UI components or reference React hooks inside domain entities.

To prevent boundary decay, we implement automated static analysis guardrails using ESLint rules and Dependency Cruiser.

1. Automated Boundary Checks via ESLint

We configure eslint-plugin-import with restricted paths to enforce the Dependency Rule at compile time:

// .eslintrc.json
{
  "plugins": ["import"],
  "rules": {
    "import/no-restricted-paths": [
      "error",
      {
        "zones": [
          {
            "target": "./src/modules/*/domain",
            "from": [
              "./src/modules/*/application",
              "./src/modules/*/infrastructure",
              "./src/modules/*/presentation"
            ],
            "message": "ARCHITECTURAL VIOLATION: Domain Layer cannot import from outer layers (Application, Infrastructure, or Presentation)."
          },
          {
            "target": "./src/modules/*/application",
            "from": [
              "./src/modules/*/infrastructure",
              "./src/modules/*/presentation"
            ],
            "message": "ARCHITECTURAL VIOLATION: Application Layer cannot import from Infrastructure or Presentation layers."
          },
          {
            "target": "./src/modules/*/infrastructure",
            "from": ["./src/modules/*/presentation"],
            "message": "ARCHITECTURAL VIOLATION: Infrastructure Layer cannot import from Presentation layer."
          }
        ]
      }
    ]
  }
}

If a developer accidentally attempts to import an HTTP client into a Domain Entity, the build fails immediately in local development and CI/CD pipelines.

2. Module Boundary Enforcement Matrix

To keep team members aligned, we enforce the following dependency access rules across all modules:

Source Layer	Allowed Imports	Forbidden Imports
Domain	Pure TypeScript utilities, internal Domain Entities / Value Objects.	Application, Infrastructure, Presentation, React, HTTP clients.
Application	Domain Layer, Application Ports, InversifyJS decorators.	Infrastructure Adapters, Presentation, UI Hooks, Browser APIs.
Infrastructure	Domain, Application Ports, External Libraries (Axios, IndexedDB).	Presentation Layer, React Components, Custom UI Hooks.
Presentation	Application Handlers, DTOs, React, UI components.	Direct Concrete Infrastructure Adapters (ApiRepository).

🏁 Series Conclusion & Architectural Summary

Over this 4-part series, we transitioned from fragile, framework-coupled React applications to a resilient, enterprise-ready frontend system:

Part 1: Diagnosed accidental technical coupling and established the fundamental Dependency Rule.
Part 2: Structured project directories into pure Domain, Application (CQRS), Infrastructure, and Presentation layers.
Part 3: Mastered production patterns including Composition Roots, Dependency Injection with InversifyJS, tag-based caching, and in-memory fakes.
Part 4: Demonstrated a practical feature workflow and established automated ESLint guardrails to maintain architectural integrity at scale.

By decoupling your business domain from volatile outer drivers, UI frameworks, and state containers, your codebase stays maintainable, simple to test, and adaptable to future technology shifts.

📦 Explore the Reference Implementation

👉 github.com/schorts99/React-Clean-Architecture

Part 3 — Advanced Frontend Engineering Patterns

Jorge Castillo — Thu, 01 Oct 2026 20:00:00 +0000

In Part 1 and Part 2, we established why frontend architectures collapse over time and how to physically structure a domain-driven codebase into isolated layers: Domain, Application, Infrastructure, and Presentation.

However, separating code into clean classes and abstract interfaces creates a practical challenge: How do we instantiate and wire these dependencies together at runtime without creating hard-coded couplings? Furthermore, how do we handle state caching, asynchronous side effects, and lightning-fast test execution without compromising our architectural boundaries?

In this third installment, we dive deep into the advanced production patterns featured in our reference implementation, React-Clean-Architecture: Dependency Injection via InversifyJS, Composition Roots for client vs. server environments, tag-based cache invalidation, and isolated testing strategies.

🏗️ Architectural Dependency & Control Flow

To understand how these advanced patterns interact, it is helpful to visualize the distinction between compile-time dependencies and runtime control flow across the application boundaries:

flowchart TB
  subgraph Presentation["PRESENTATION LAYER"]
    React["React View / UI Component"]
    ViewModel["Custom ViewModel Hook"]
    React -->|"uses"| ViewModel
  end

  ViewModel -->|"resolves via IoC Container"| Handlers

  subgraph Application["APPLICATION LAYER"]
    Handlers["Command / Query Handlers"]
    Ports["Primary Ports"]
    Domain["Domain Entities / Value Objects<br/>(Pure TypeScript - Zero External Dependencies)"]

    Handlers -->|"implements"| Ports
    Handlers -->|"orchestrates"| Domain
    Ports -->|"depends on"| Domain
  end

  Ports -.->|"Inversion of Control"| Infra

  subgraph Infrastructure["INFRASTRUCTURE LAYER"]
    ApiRepo["ApiCartRepository"]
    Cache["CacheManager"]
    Composition["Composition Root / InversifyJS Container Setup"]
    ICart["ICartRepository"]

    ApiRepo -->|"implements Port"| ICart
  end

Notice how the Infrastructure Layer points inward by implementing the ports defined by the Application Layer, fulfilling the Dependency Inversion Principle.

🔌 Pattern 1: Dependency Injection & The Composition Root

When using abstract ports (e.g., ICartRepository), application code or custom hooks should never manually instantiate infrastructure adapters with statements like new ApiCartRepository(). Doing so reintroduces direct coupling to concrete infrastructure and breaks testability.

Instead, we use Inversion of Control (IoC) powered by InversifyJS to resolve dependencies dynamically at runtime.

1. Defining Symbols & Binding Contracts

We define unique Symbol identifiers for our application ports and services to guarantee type safety during dependency lookup:

export const TYPES = {
  // Ports / Repositories
  CARTS_REPOSITORY: Symbol.for("CARTS_REPOSITORY"),
  PRODUCTS_CATALOG_SERVICE: Symbol.for("PRODUCTS_CATALOG_SERVICE"),

  // Command & Query Handlers
  ADD_ITEM_TO_CART_COMMAND_HANDLER: Symbol.for("ADD_ITEM_TO_CART_COMMAND_HANDLER"),
  GET_CART_SUMMARY_QUERY_HANDLER: Symbol.for("GET_CART_SUMMARY_QUERY_HANDLER"),

  // Infrastructure Services
  CACHE: Symbol.for("CACHE"),
  HTTP_CLIENT: Symbol.for("HTTP_CLIENT"),
};

2. The Composition Root

The Composition Root is the single location in your application where the object graph is constructed. It is the only module in the entire system allowed to import concrete infrastructure adapters.

export function createApplicationContainer(environment: "production" | "test" | "ssr") {
  const container = new Container({ defaultScope: "Singleton" });

  // 1. Core Infrastructure Services
  container.bind<CacheManager>(TYPES.CACHE).to(CacheManager);

  // 2. Bind Infrastructure Adapters based on execution environment
  if (environment === "production") {
    container.bind<ICartRepository>(TYPES.CARTS_REPOSITORY).to(ApiCartRepository);
  } else if (environment === "ssr") {
    // SSR environment might use a direct internal API adapter or specialized cache
    container.bind<ICartRepository>(TYPES.CARTS_REPOSITORY).to(ApiCartRepository);
  } else {
    // In-memory fake repository for lightning-fast testing and offline development
    container.bind<ICartRepository>(TYPES.CARTS_REPOSITORY).to(InMemoryCartRepository);
  }

  // 3. Bind Application Use Case Handlers
  container.bind<AddItemToCartCommandHandler>(
    TYPES.ADD_ITEM_TO_CART_COMMAND_HANDLER
  ).to(AddItemToCartCommandHandler);

  container.bind<GetCartSummaryQueryHandler>(
    TYPES.GET_CART_SUMMARY_QUERY_HANDLER
  ).to(GetCartSummaryQueryHandler);

  return container;
}

3. Exposing IoC to React via Context

To consume these dependencies inside React without coupling presentation code to InversifyJS directly, we wrap our application in a lightweight Dependency Injection Provider:

import React, { createContext, useContext } from "react";
import { Container } from "inversify";

const DependencyInjectionContext = createContext<Container null |>(null);

export const DependencyInjectionProvider: React.FC<{
  container: Container;
  children: React.ReactNode;
}> = ({ container, children }) => (
  <DependencyInjectionContext.Provider value="{container}">
    {children}
  </DependencyInjectionContext.Provider>
);

export function useDependency<T>(serviceIdentifier: symbol): T {
  const container = useContext(DependencyInjectionContext);

  if (!container) {
    throw new Error("useDependency must be used within a DependencyInjectionProvider");
  }

  return container.get<T>(serviceIdentifier);
}

By changing the environment flag passed to createApplicationContainer, we can swap the entire underlying infrastructure (REST API vs. IndexedDB vs. In-Memory) across the application without modifying a single UI component or business rule.

⚡ Pattern 2: Tag-Based Cache Invalidation

One of the hardest problems in rich frontend applications is keeping local UI state synchronized with underlying domain mutations without over-fetching network resources or writing imperative state updates across dozens of components.

In React-Clean-Architecture, query handlers manage local caching using Tag-Based Invalidation. Queries tag the domain entities they retrieve, and Commands emit architectural invalidation tags upon successful mutations.

1. The Query Handler with Tag Metadata

export interface CartSummaryDTO {
  id: string;
  itemCount: number;
  totalFormatted: string;
}

export class GetCartSummaryQueryHandler {
  readonly cacheTags = ["cart", "pricing"];

  constructor(private readonly cartRepository: ICartRepository) {}

  async execute(cartId: string): Promise<CartSummaryDTO> {
    const cart = await this.cartRepository.getById(cartId);

    if (!cart) {
      throw new Error("Cart not found");
    }

    return {
      id: cart.id,
      itemCount: cart.items.reduce((sum, item) => sum + item.quantity.value, 0),
      totalFormatted: `$${cart.calculateTotal().amount.toFixed(2)}`,
    };
  }
}

2. Infrastructure Cache Manager

When a write operation like AddItemToCartCommandHandler succeeds, the infrastructure cache manager processes the invalidation tags:

type InvalidationCallback = () => void;

export class CacheManager {
  private cache = new Map<string, { data: unknown; tags: string[] }>();
  private subscribers = new Map<string, Set<InvalidationCallback>>();

  set(key: string, data: unknown, tags: string[]): void {
    this.cache.set(key, { data, tags });
  }

  get<T>(key: string): T | null {
    return (this.cache.get(key)?.data as T) || null;
  }

  subscribe(tag: string, callback: InvalidationCallback): () => void {
    if (!this.subscribers.has(tag)) {
      this.subscribers.set(tag, new Set());
    }

    this.subscribers.get(tag)!.add(callback);

    return () => {
      this.subscribers.get(tag)?.delete(callback);
    };
  }

  invalidateTags(tagsToInvalidate: string[]): void {
    for (const [key, entry] of this.cache.entries()) {
      const hasMatchingTag = entry.tags.some((tag) => tagsToInvalidate.includes(tag));

      if (hasMatchingTag) {
        this.cache.delete(key);
      }
    }

    // Notify active UI subscribers
    for (const tag of tagsToInvalidate) {
      const callbacks = this.subscribers.get(tag);

      if (callbacks) {
        callbacks.forEach((cb) => cb());
      }
    }
  }
}

3. Bridging Caching to Presentation via Custom ViewModel Hooks

React components consume these use-case handlers through clean custom hooks that encapsulate execution lifecycle and auto-subscribe to tag invalidations:

export function useCartSummaryViewModel(cartId: string) {
  const queryHandler = useDependency<GetCartSummaryQueryHandler>(TYPES.GET_CART_SUMMARY_QUERY_HANDLER);
  const cacheManager = useDependency<CacheManager>(TYPES.CACHE);
  const [data, setData] = useState<CartSummaryDTO null |>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<Error null |>(null);

  const fetchSummary = useCallback(async () => {
    setLoading(true);

    try {
      const cacheKey = `cart_summary_${cartId}`;
      const cached = cacheManager.get<CartSummaryDTO>(cacheKey);

      if (cached) {
        setData(cached);
        setLoading(false);

        return;
      }

      const result = await queryHandler.execute(cartId);

      cacheManager.set(cacheKey, result, queryHandler.cacheTags);
      setData(result);
      setError(null);
    } catch (err) {
      setError(err as Error);
    } finally {
      setLoading(false);
    }
  }, [cartId, queryHandler, cacheManager]);

  useEffect(() => {
    fetchSummary();

    // Subscribe to cache invalidation tags
    const unsubscribes = queryHandler.cacheTags.map((tag) =>
      cacheManager.subscribe(tag, fetchSummary)
    );

    return () => unsubscribes.forEach((unsub) => unsub());
  }, [fetchSummary, cacheManager, queryHandler.cacheTags]);

  return { data, loading, error, refresh: fetchSummary };
}

When AddItemToCartCommandHandler completes, it requests an invalidation of the "cart" tag. Any active React hook subscribed to queries tagged with "cart" automatically triggers a background re-fetch, keeping the UI completely in sync without manual state syncing across React components.

🧪 Pattern 3: Lightning-Fast Isolated Testing Strategies

A major benefit of decoupling domain rules and use cases from React and browser APIs is the drastic impact on test suite execution speed and reliability.

We categorize testing into two distinct tiers:

1. Pure Domain Unit Tests (Zero Mocks)

Domain entities and value objects are pure TypeScript. They require no mocking libraries (jest.fn()), JSDOM, or React testing utilities.

describe("Cart Entity (Domain Unit Test)", () => {
  it("should aggregate quantity when adding duplicate items", () => {
    const cart = Cart.create("cart-1");
    const itemA = CartItem.create("prod-100", Money.create(50), 1);
    const itemB = CartItem.create("prod-100", Money.create(50), 2);

    cart.addItem(itemA);
    cart.addItem(itemB);

    expect(cart.items).toHaveLength(1);
    expect(cart.items[0].quantity.value).toBe(3);
    expect(cart.calculateTotal().amount).toBe(150);
  });

  it("should throw an error when adding money with mismatched currencies", () => {
    const usd = Money.create(100, "USD");
    const eur = Money.create(100, "EUR");

    expect(() => usd.add(eur)).toThrow("Currency mismatch.");
  });
});

2. Use Case Handler Tests with In-Memory Fakes

Instead of mocking HTTP network responses with libraries like MSW or intercepting fetch calls, application use-case handlers are tested using fast In-Memory Fake Adapters plugged directly into the test IoC container.

describe("AddItemToCartCommandHandler (Application Integration Test)", () => {
  it("should orchestrate cart item addition using fake infrastructure", async () => {
    // 1. Arrange: Instantiate container configured for testing
    const container = createApplicationContainer("test");
    const fakeRepo = container.get<ICartRepository>(TYPES.CARTS_REPOSITORY);

    // Seed initial state into the in-memory repository
    await fakeRepo.save(Cart.create("cart-99"));

    const handler = container.get<AddItemToCartCommandHandler>(TYPES.ADD_ITEM_TO_CART_COMMAND_HANDLER);

    // 2. Act: Execute Command
    await handler.execute({ cartId: "cart-99", productId: "prod-1", quantity: 2 });

    // 3. Assert: Verify state in fake persistence
    const updatedCart = await fakeRepo.getById("cart-99");
    expect(updatedCart?.items).toHaveLength(1);
    expect(updatedCart?.items[0].quantity.value).toBe(2);
  });
});

Because these tests execute entirely in Node/Vite without JSDOM overhead or actual HTTP networks, hundreds of business logic scenarios run in fractions of a second—eliminating flaky CI builds entirely.

🛠️ Summary of Advanced Engineering Patterns

Pattern	Problem Solved	Clean Architecture Mechanism
Composition Root & IoC	Prevents direct coupling to concrete infrastructure drivers.	InversifyJS container binding abstract ports to adapters at application boot.
Tag-Based Caching	Prevents state drift and over-fetching after state mutations.	Queries register tags; Commands trigger tag invalidations through event handlers.
In-Memory Fakes	Eliminates slow, brittle network mocks in unit/integration tests.	Swap real API adapters for in-memory repositories in test containers.
Pure Domain Testing	Eliminates DOM setup overhead and test flakiness.	Tests execute against pure TypeScript classes without JSDOM or framework dependencies.

📢 Up Next...

We have explored the architectural principles, directory structures, and advanced production patterns. But how does this work in day-to-day developer workflows when building a new feature from scratch?

Coming up next in Part 4: Practical Guide — Adding Features & Architectural Rules. We will step through adding a brand-new feature to an existing Clean Architecture codebase—from domain modeling down to registering handlers and connecting UI components—and outline automated guardrails (ESLint rules, boundary checks) to enforce these boundaries as your engineering team scales.

Explore the full reference codebase on GitHub:

👉 github.com/schorts99/React-Clean-Architecture

Part 2 - The How: Architectural Layers & Domain-Driven Design

Jorge Castillo — Wed, 23 Sep 2026 22:30:06 +0000

In Part 1, we established why modern React applications degrade over time: unmanaged dependencies, framework lock-in, and the "Fat Component" anti-pattern. The remedy is the Dependency Rule—ensuring core business logic never depends on volatile outer infrastructure like UI frameworks, state management libraries, or REST API endpoints.

Now, we move from principle to execution. How do we physically structure a React project to enforce these boundaries without devolving into folder chaos?

In this second installment, we break down the modular architecture of our reference repository, React-Clean-Architecture, exploring how to model domain entities, enforce boundary constraints, orchestrate application use cases, and implement resilient infrastructure adapters.

📁 Feature-First, Module-Oriented Directory Structure

Instead of grouping code by technical role (/components, /hooks, /services), Clean Architecture organizes the codebase into domain modules. Each module represents a distinct business boundary (a Bounded Context in Domain-Driven Design terminology) and encapsulates its own three-layer architecture.

src/
├── modules/
│   └── shopping-cart/             <-- Bounded Context / Domain Module
│       ├── domain/                <-- Pure TypeScript (Zero External Dependencies)
│       │   ├── entities/          <-- Cart.ts, CartItem.ts
│       │   ├── value-objects/     <-- Money.ts, Quantity.ts
│       │   └── errors/            <-- InvalidQuantityError.ts
│       │
│       ├── application/           <-- Use Cases & Workflow Orchestration
│       │   ├── commands/          <-- AddItemToCartCommand.ts
│       │   ├── queries/           <-- GetCartSummaryQuery.ts
│       │   └── ports/             <-- ICartRepository.ts (Primary & Secondary Ports)
│       │
│       ├── infrastructure/        <-- Outer Drivers & Technology Implementations
│       │   ├── adapters/          <-- ApiCartRepository.ts, IndexedDBCartRepository.ts
│       │   └── mappers/           <-- CartMapper.ts
│       │
│       └── presentation/          <-- React UI Components & Custom Hooks
│           ├── components/        <-- CartView.tsx, CheckoutButton.tsx
│           └── hooks/             <-- useCartViewModel.ts

By enforcing this structure, any engineer working inside /domain or /application can immediately see that importing anything from /presentation or /infrastructure violates the architecture.

💎 Layer 1: The Domain Layer (Core Business Invariants)

The Domain Layer sits at the absolute center of your application. It contains no React imports, no fetch calls, and no browser storage references. It is composed entirely of pure TypeScript primitives, Entities, and Value Objects.

1. Value Objects

Value Objects are immutable types defined entirely by their attributes rather than an identity. They encapsulate validation rules, type safety, and domain calculations.

// domain/value-objects/Quantity.ts
export class Quantity {
  private constructor(readonly value: number) {
    if (value <= 0 || !Number.isInteger(value)) {
      throw new Error("Quantity must be a positive integer.");
    }
  }

  static create(value: number): Quantity {
    return new Quantity(value);
  }

  add(other: Quantity): Quantity {
    return new Quantity(this.value + other.value);
  }
}

// domain/value-objects/Money.ts
export class Money {
  private constructor(readonly amount: number, readonly currency: string) {
    if (amount < 0) {
      throw new Error("Money amount cannot be negative.");
    }
  }

  static create(amount: number, currency = "USD"): Money {
    return new Money(amount, currency);
  }

  add(other: Money): Money {
    if (this.currency !== other.currency) {
      throw new Error("Currency mismatch.");
    }
    return new Money(this.amount + other.amount, this.currency);
  }

  multiply(factor: number): Money {
    return new Money(this.amount * factor, this.currency);
  }
}

2. Domain Entities

Entities possess a unique identity (id) that persists across state changes. They enforce business rules (invariants) whenever state mutations occur.

// domain/entities/CartItem.ts
export class CartItem {
  private constructor(
    readonly productId: string,
    readonly unitPrice: Money,
    private _quantity: Quantity
  ) {}

  static create(productId: string, unitPrice: Money, quantity: number): CartItem {
    return new CartItem(productId, unitPrice, Quantity.create(quantity));
  }

  get quantity(): Quantity {
    return this._quantity;
  }

  get totalPrice(): Money {
    return this.unitPrice.multiply(this._quantity.value);
  }

  increaseQuantity(additional: Quantity): CartItem {
    return new CartItem(
      this.productId,
      this.unitPrice,
      this._quantity.add(additional)
    );
  }
}

// domain/entities/Cart.ts
export class Cart {
  private constructor(
    readonly id: string,
    private _items: CartItem[],
    private _discountCode?: string
  ) {}

  static create(id: string, items: CartItem[] = []): Cart {
    return new Cart(id, items);
  }

  get items(): readonly CartItem[] {
    return [...this._items];
  }

  // Business Invariant: Business rules computed directly inside domain boundary
  calculateTotal(): Money {
    const subtotal = this._items.reduce(
      (sum, item) => sum.add(item.totalPrice),
      Money.create(0)
    );
    return subtotal;
  }

  addItem(newItem: CartItem): void {
    const existingIndex = this._items.findIndex((item) => item.productId === newItem.productId);
    if (existingIndex >= 0) {
      this._items[existingIndex] = this._items[existingIndex].increaseQuantity(newItem.quantity);
    } else {
      this._items.push(newItem);
    }
  }
}

⚙️ Layer 2: The Application Layer (CQRS & Ports)

The Application Layer orchestrates use cases. It tells the domain entities what to do and communicates with outer systems using abstract interfaces called Ports.

To keep write operations distinct from read operations, we use a lightweight CQRS (Command Query Responsibility Segregation) pattern:

Commands: Intentional actions that alter application state (e.g., AddItemToCartCommand).
Queries: Read-only requests that retrieve formatted data for the view without side effects (e.g., GetCartSummaryQuery).

1. Defining Application Ports

The application layer defines what data access services it requires without caring how they are implemented.

// application/ports/ICartRepository.ts
export interface ICartRepository {
  getById(cartId: string): Promise<Cart | null>;
  save(cart: Cart): Promise<void>;
}

// application/ports/IProductCatalogService.ts
export interface IProductCatalogService {
  getPrice(productId: string): Promise<Money>;
}

2. Implementing Command & Query Handlers

Command handlers execute state mutations, while Query handlers project data directly for consumption.

// application/commands/AddItemToCartHandler.ts
export class AddItemToCartHandler {
  constructor(
    private readonly cartRepository: ICartRepository,
    private readonly catalogService: IProductCatalogService
  ) {}

  async execute(command: { cartId: string; productId: string; quantity: number }): Promise<void> {
    const cart = await this.cartRepository.getById(command.cartId);
    if (!cart) {
      throw new Error("Cart not found.");
    }

    const price = await this.catalogService.getPrice(command.productId);
    const item = CartItem.create(command.productId, price, command.quantity);

    cart.addItem(item); // Enforces internal domain rules

    await this.cartRepository.save(cart); // Persists via abstract port
  }
}

🔌 Layer 3: The Infrastructure Layer (Adapters & Mappers)

The Infrastructure Layer fulfills the abstract contracts defined by the application layer. It handles network protocol execution, IndexedDB caching, or third-party client integrations.

Data Mappers: Isolating API Schemas

External API payload formats should never contaminate inner domain entities. Mappers explicitly transform raw Data Transfer Objects (DTOs) into clean domain objects.

// infrastructure/mappers/CartMapper.ts
export interface ApiCartResponseDTO {
  cart_id: string;
  line_items: Array<{
    product_id: string;
    unit_amount: number;
    currency_code: string;
    qty: number;
  }>;
}

export class CartMapper {
  static toDomain(raw: ApiCartResponseDTO): Cart {
    const items = raw.line_items.map((item) =>
      CartItem.create(
        item.product_id,
        Money.create(item.unit_amount, item.currency_code),
        item.qty
      )
    );
    return Cart.create(raw.cart_id, items);
  }

  static toDTO(cart: Cart): Record<string, unknown> {
    return {
      cart_id: cart.id,
      line_items: cart.items.map((item) => ({
        product_id: item.productId,
        unit_amount: item.unitPrice.amount,
        currency_code: item.unitPrice.currency,
        qty: item.quantity.value,
      })),
    };
  }
}

🖥️ Layer 4: The Presentation Layer (Thin React Views)

With domain logic and use case orchestration safely encapsulated in inner layers, UI components become extraordinarily clean. React components focus entirely on presentation, event listening, and rendering.

// presentation/hooks/useAddToCartViewModel.ts
export const useAddToCartViewModel = () => {
  const [isLoading, setIsLoading] = useState(false);
  // Inject handler via container/context in production
  const handler = useDependency<AddItemToCartHandler>("AddItemToCartHandler");

  const executeAddToCart = async (params: { cartId: string; productId: string; quantity: number }) => {
    setIsLoading(true);
    try {
      await handler.execute(params);
    } finally {
      setIsLoading(false);
    }
  };

  return { executeAddToCart, isLoading };
};

// presentation/components/AddToCartButton.tsx
export const AddToCartButton = ({ cartId, productId }: { cartId: string; productId: string }) => {
  const { executeAddToCart, isLoading } = useAddToCartViewModel();

  const handleClick = () => {
    executeAddToCart({ cartId, productId, quantity: 1 });
  };

  return (
    <button onClick={handleClick} disabled={isLoading}>
      {isLoading ? "Adding..." : "Add to Cart"}
    </button>
  );
};

📊 Summary of Architectural Responsibilities

Layer	Responsibility	Allowed Dependencies
Domain	Modeling core business rules, Entities, & Value Objects.	None (Pure TypeScript)
Application	Use-case orchestration (CQRS) & Port interface definitions.	Domain Layer only
Infrastructure	Database drivers, HTTP adapters, and DTO Mappers.	Domain & Application Layers
Presentation	React components, UI state, rendering hooks, & views.	Application & Domain Layers

📢 Up Next...

Now that we have separated our codebase into domain entities, application ports, adapters, and thin UI views, how do we wire all these dependencies together dynamically at runtime without manually instantiating classes everywhere?

Coming up next in Part 3: Advanced Frontend Engineering Patterns. We will explore Dependency Injection with InversifyJS, Composition Roots for browser vs. SSR environments, tag-based cache invalidation, and lightning-fast isolated testing strategies.

Follow along in the reference implementation on GitHub:

👉 github.com/schorts99/React-Clean-Architecture

Part 1 - The Why: Why Architecture Matters on the Frontend

Jorge Castillo — Tue, 15 Sep 2026 00:38:27 +0000

Most modern React applications start out as triumphs of developer velocity. You spin up a project with Vite, pull in a few UI libraries, throw together some useEffect hooks, and ship features in hours. But as team size grows and feature complexity scales, that initial speed decays into structural inertia.

Suddenly, simple UI tweaks break unrelated business workflows, refactoring network calls requires rewriting component tests, and adding a new state variable feels like diffusing a bomb.

This degradation isn't caused by bad developers or missing framework features—it is the direct consequence of accidental coupling. In this first installment of our series, we unpack why unmanaged dependencies destroy frontend maintainability, analyze the true cost of framework lock-in, and introduce the core rules that keep your domain logic bulletproof over time.

🛑 The "Fat Component" Anti-Pattern

In typical React applications, components naturally become magnets for every operational concern in the system. Consider a standard component responsible for checking out a shopping cart:

// ❌ Accidental Coupling: Everything living inside the UI layer
export const CheckoutButton = ({ cartId }: { cartId: string }) => {
  const [loading, setLoading] = useState(false);

  const handleCheckout = async () => {
    setLoading(true);

    // 1. Fetching raw data directly from an API endpoint
    const res = await fetch(`/api/carts/${cartId}`);
    const cart = await res.json();

    // 2. Business Rule: Carts over $100 get free shipping, but require a minimum of 2 items
    let shippingFee = 15;

    if (cart.total > 100 && cart.items.length >= 2) {
      shippingFee = 0;
    }

    // 3. Interfacing with local storage caching directly
    localStorage.setItem('last_checkout_total', cart.total + shippingFee);

    // 4. Executing payment network mutation
    await fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify({ cartId, amount: cart.total + shippingFee }),
    });

    setLoading(false);
  };

  return <button onClick={handleCheckout}>{loading ? 'Processing...' : 'Checkout'}</button>;
};

When UI components coordinate HTTP requests, evaluate domain rules, mutate local browser storage, and manage rendering logic simultaneously, you incur severe architectural liabilities:

Framework Lock-in: Your core business calculations (e.g., shipping rules) are tangled directly inside React lifecycle hooks and synthetic event handlers. Switching frameworks or reusing logic outside React becomes impossible.
Brittle Testing: To test whether the shipping rule works, you can't simply run a 2-millisecond unit test. You must mock fetch, mock localStorage, render a React DOM node, and simulate user clicks.
Data Schema Leakage: When backend API response schemas change, your presentation code breaks instantly across dozens of UI components.

💸 The High Cost of UI-Centric Architecture

Why do codebases decay so rapidly when business logic lives inside presentation components? Let's break down the technical debt multiplier:

Problem Domain	UI-Centric Approach	Clean Architecture Approach
Testing Overhead	Heavy reliance on JSDOM, React Testing Library, and complex mock providers.	Fast unit tests in pure TypeScript without DOM or network dependencies.
API Instability	Breaking API payload changes require sweeping refactors across UI components.	Mappers isolate external API contracts from internal domain entities.
State Management Drift	Logic gets duplicated across React state, Redux, Zustand, and query caches.	Application state logic is centralized inside explicit Use Cases.
Framework Upgrades	Major React version jumps or migration to SSR risk breaking business rules.	Core business rules have zero dependencies on React or any third-party framework.

🎯 The Core Architectural Principle: The Dependency Rule

To eliminate accidental coupling, we apply the Dependency Rule, the central pillar of Clean Architecture:

Source code dependencies must point inward, toward high-level policies.

flowchart TB
    subgraph UI["UI & Frameworks<br/>(React, Browser APIs, HTTP)"]
        direction TB
    end

    UI -.-> Outer["Outer Layer (Volatile)"]
    UI --> Adapters

    subgraph Adapters["Infrastructure Adapters<br/>(Fetch Client, IndexedDB, LocalStorage)"]
        direction TB
    end

    Adapters -.-> AdapterLabel["Adapter Layer"]
    Adapters --> UseCases

    subgraph UseCases["Application Use Cases<br/>(Commands & Queries)"]
        direction TB
    end

    UseCases -.-> Orchestration["Orchestration"]
    UseCases --> Core

    subgraph Core["Core Domain<br/>(Entities & Business Rules)"]
        direction TB
    end

    Core -.-> Inner["Inner Layer (Stable)"]

    style UI fill:#f9f9f9,stroke:#333,stroke-width:2px
    style Adapters fill:#e8f4f8,stroke:#333,stroke-width:2px
    style UseCases fill:#e8f8e8,stroke:#333,stroke-width:2px
    style Core fill:#f8e8e8,stroke:#333,stroke-width:2px

The Inviolable Rule

Nothing in an inner layer can know anything about something in an outer layer.

The Domain Layer (Entities, Value Objects) knows nothing about Use Cases, REST APIs, or React.
The Application Layer (Use Cases, Ports) knows nothing about React components or specific database drivers.
The Presentation & Infrastructure Layers (React UI, Axios, IndexedDB) depend inward on abstract interfaces defined by the application layer.

By forcing dependencies to point strictly inward, your core business rules become completely decoupled from UI frameworks, state management libraries, and external APIs.

🔄 Inversion of Control in Action

How does an inner layer trigger an operation (like fetching a record or storing a token) without knowing about the concrete driver executing it? Through Inversion of Control (IoC) via Ports & Adapters.

Instead of importing an HTTP client directly inside a business rule, the Application layer defines an abstract Port (an interface):

// 1. Application Port (Owned by the core application)
export interface ICartRepository {
  getById(cartId: string): Promise<Cart>;
  save(cart: Cart): Promise<void>;
}

The outer Infrastructure layer implements this port via an Adapter:

// 2. Infrastructure Adapter (Outer layer)
export class ApiCartRepository implements ICartRepository {
  async getById(cartId: string): Promise<Cart> {
    const res = await fetch(`/api/carts/${cartId}`);
    const data = await res.json();
    return CartMapper.toDomain(data); // Maps API schema to pure Domain Entity
  }

  async save(cart: Cart): Promise<void> {
    await fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify(CartMapper.toDTO(cart)),
    });
  }
}

Because the core domain relies solely on the ICartRepository interface, you can swap ApiCartRepository for an InMemoryCartRepository during testing or an IndexedDBCartRepository for offline support without modifying a single line of business logic.

🧪 Testing as an Architectural Indicator

One of the most immediate feedback loops of a Clean Architecture setup is test suite velocity.

When your business logic is decoupled from React and browser APIs, testing a complex domain feature doesn't require launching a headless browser or mounting virtual DOM trees.

// ✅ Pure Unit Test: Zero DOM, zero network mocks, runs in milliseconds
describe('Cart Shipping Calculation', () => {
  it('should apply free shipping for orders over $100 with at least 2 items', () => {
    const cart = Cart.create({ items: [itemA, itemB], totalAmount: 120 });

    expect(cart.calculateShippingFee()).toBe(0);
  });

  it('should charge shipping for orders over $100 with less than 2 items', () => {
    const cart = Cart.create({ items: [itemA], totalAmount: 150 });

    expect(cart.calculateShippingFee()).toBe(15);
  });
});

Because this test interacts purely with TypeScript domain objects, hundreds of business rule scenarios can execute in a fraction of a second in your CI/CD pipeline—giving your team instant feedback without test flakiness.

📢 Up Next...

Decoupling logic from the UI sounds great in theory, but how do you physically organize a codebase to enforce these boundaries without falling into folder chaos?

Coming up next in Part 2: The How — Architectural Layers & Domain-Driven Design. We will examine how to structure a domain-driven codebase in strict TypeScript, build pure Domain Entities and Value Objects, and implement CQRS workflows using application-owned ports.

Explore the reference implementation anytime on GitHub:

👉 github.com/schorts99/React-Clean-Architecture

Reviving Budget Hardware with Omarchy: Lightweight Elegance on an Intel Celeron

Jorge Castillo — Thu, 27 Aug 2026 20:50:00 +0000

When testing opinionated Linux distributions, the ultimate benchmark isn't how smoothly they run on a workstation with 16 cores and a high-end GPU—it's how gracefully they perform on budget, resource-constrained hardware. Enter Omarchy, the "omakase" Arch-based distribution created by David Heinemeier Hansson (DHH). Built around the Hyprland tiling window manager and explicitly tailored for modern developer productivity, Omarchy proves that a curated desktop environment doesn't require a heavy computing footprint.

Running Omarchy 4.0.0 on an entry-level laptop built around an Intel Celeron N4020 CPU demonstrates how deliberate software curation turns modest hardware into a fast, highly capable development machine.

💻 Hardware & System Overview

Below is the environment breakdown from our test run:

Category	Specification / Details
Hardware / PC Model	ASUS C204M
Processor	Intel® Celeron® N4020 (2 cores / 2 threads) @ 2.80 GHz
Graphics	Integrated Intel UHD Graphics 600
Display	11" Built-in Display (1366x768 @ 60 Hz)
RAM Utilization	2.69 GiB / 3.68 GiB (~73% load)
Storage / Root	15.66 GiB / 27.10 GiB (~58% used) on Btrfs
OS & Kernel	Omarchy 4.0.0-1 (Linux Kernel 7.1.8-arch1-3)
Compositor	Hyprland 0.56.2 (Wayland)

🚀 The Developer Experience: What Makes Omarchy Special

Omarchy isn't just an Arch installer with custom dots; it's an opinionated operating system designed to eliminate setup friction and let you write code immediately.

1. Zero-Friction Language Setup via Menus

Setting up language runtimes on a fresh Linux install often involves hunting down version managers (like asdf, nvm, or pyenv), configuring shell initialization scripts, and managing system paths. Omarchy streamlines this entirely.

Through its integrated menu system, installing a programming language or developer stack is as simple as launching the system menu, picking a language (Node.js, Ruby, Python, Go, Rust), and hitting Enter. The system automatically installs the necessary version managers, configures environment variables, and makes runtime binaries globally available in your PATH. On low-spec hardware, avoiding manual shell configuration bugs saves precious time and friction.

2. Pre-Configured, Production-Ready NeoVim

Rather than leaving you with a blank slate or forcing you to build a custom init.lua setup from scratch, Omarchy comes with an out-of-the-box NeoVim configuration tuned for modern development:

Pre-baked LSP & Treesitter: Syntax highlighting, auto-formatting, and Language Server Protocol integration work out of the box for major languages.
Cohesive Theme Integration: NeoVim automatically respects the system-wide aesthetic (Tokyo Night in this setup), ensuring seamless visual transitions between your terminal windows and editor panes.
Optimized Performance: Keybindings, fuzzy finders (like telescope or fzf), and file trees launch instantly without heavy startup latency, even on a dual-core CPU.

3. Tiling Window Efficiency on Small Screens

On an 11-inch display running at 1366 x 768, traditional desktop window managers waste massive amounts of visual real estate with window borders, title bars, and heavy panel docks. Hyprland maximizes every pixel:

Applications auto-tile side-by-side or stack neatly into workspaces.
Navigation happens entirely via keyboard shortcuts, eliminating mouse travel.
Animations remain smooth without dropping frames, thanks to Wayland hardware acceleration on Intel UHD Graphics 600.

⚡ Performance Deep Dive: Living with Low Specs

Operating on a machine with 3.68 GiB of usable RAM and an Intel Celeron N4020 usually means constant stuttering and high swap usage. Omarchy subverts this expectation through careful architectural choices:

Wayland Compositing without Bloat: Hyprland handles window composition directly on the GPU, leaving the dual-core Celeron free to handle background tasks and code compilation.
Lightweight Terminal Choice: Running foot (a fast, lightweight Wayland terminal emulator) keeps system memory usage remarkably low while delivering sub-millisecond rendering times.
Btrfs Storage Optimizations: The root partition runs on Btrfs, enabling transparent file compression and fast subvolume snapshots. This maximizes usable disk space on tight 32 GB or 64 GB internal drives while maintaining fast read/write speeds.

💡 Developer Evaluation: Should You Try Omarchy?

Before jumping in, it helps to understand who Omarchy is built for—and where it might not fit your workflow.

🟢 You Should Try Omarchy If:

You want a keyboard-driven workflow without spending days rice-ing dotfiles: Configuring Hyprland, Waybar, and NeoVim from scratch takes hours of tweaking. Omarchy provides DHH's polished, cohesive setup instantly.
You are reviving budget or older hardware: It turns low-power CPUs and limited-RAM devices into fast, responsive coding terminals.
You appreciate "Omakase" sensible defaults: If you prefer curated tooling (standardized themes, opinionated keybindings, terminal-first workflows) over configuring every micro-setting yourself, you will feel right at home.
You want the benefits of Arch Linux without manual maintenance: You get access to the Arch User Repository (AUR) and rolling updates wrapped in an accessible, pre-configured distribution.

🔴 You Might Want to Skip Omarchy If:

You rely heavily on floating windows or traditional GUIs: Hyprland is a tiling window manager at heart. If your workflow relies on drag-and-drop window management and mouse-heavy navigation, the learning curve will feel steep.
You require deep custom desktop layout changes: While you can modify configurations, Omarchy is intentionally opinionated. Customizing away from its core defaults defeats much of its plug-and-play value.

📋 Verdict

Omarchy delivers on DHH's "omakase" philosophy: sensible defaults, curated developer tooling, and zero visual clutter. By eliminating background daemon overhead and pre-configuring essential tools—from one-click language installations to a fully prepped NeoVim environment—it transforms an inexpensive Celeron laptop into a nimble, surprisingly productive development machine.

Presenting: The Blueprint for Scalable Frontend Systems — Clean Architecture & DDD in React

Jorge Castillo — Tue, 18 Aug 2026 19:13:12 +0000

As React applications grow from simple prototypes into complex, mission-critical systems, they almost universally hit a wall. Components swell into “Fat Components” that manage UI rendering, coordinate network requests, execute business rules, handle local caching, and interface directly with database schemas — all at once.

When technical boundaries blur, software becomes fragile and change becomes expensive.

To build frontend systems that scale alongside business needs without collapsing under technical debt, we need to apply the same architectural rigor long practiced in backend engineering: strict separation of concerns, explicit domain modeling, and inversion of control.

We are launching a comprehensive 4-part series: The Blueprint for Scalable Frontend Systems, driven by our open-source reference implementation, React-Clean-Architecture.

🗺️ What to Expect in This Series

Throughout this series, we will break down how to design, structure, and implement a production-grade React application in strict TypeScript where business logic, application orchestration, infrastructure adapters, and UI components remain completely decoupled.

Here is the roadmap of what we will cover across the 4 parts:

💡 Part 1: The Why — Why Architecture Matters on the Frontend

We start with the core problem: accidental coupling in modern SPA development. We will explore how unmanaged dependencies leak business logic into view components, lock applications into specific third-party drivers, and make testing slow and brittle. We will introduce the Dependency Rule as the foundational principle for keeping inner layers completely independent of frameworks like React, browser APIs, or network protocols.

🏗️ Part 2: The How — Architectural Layers & Domain-Driven Design

Next, we dive deep into the codebase layout. Moving away from technical-role folders (/components, /services), we explore a module-oriented structure where each business context encapsulates its own domain, application, and infrastructure layers. We will look at:

Domain Layer: Modeling business invariants using pure Entities and Value Objects.
Application Layer: Defining workflows through CQRS (Commands & Queries) and application-owned Ports.
Infrastructure Layer: Implementing persistent adapters (such as IndexedDB or REST clients) behind application ports without leaking driver details.

⚡ Part 3: Advanced Frontend Engineering Patterns

In the third installment, we tackle real-world production challenges. We will examine:

Tag-Based Cache Invalidation: Automatically clearing cached query results when commands execute state mutations.
Composition Root & Inversion of Control: Using InversifyJS to wire dependencies dynamically based on the runtime environment (browser vs. SSR/server).
Isolated Testing Strategies: Unit testing domain rules in pure TypeScript and testing use-case handlers using lightning-fast in-memory fakes instead of real databases or network mocks.

🛠️ Part 4: Practical Guide — Adding Features & Architectural Rules

In the final part, we turn theory into a repeatable development process. We will walk step-by-step through adding a brand-new feature to an existing Clean Architecture codebase — from defining the initial domain entity down to registering handlers and connecting UI components. We will also outline the fundamental architectural guardrails every team should enforce to prevent accidental dependency violations as the team expands.

📦 The Reference Repository

This series isn’t just theoretical — it is built entirely around a fully working, production-ready codebase featuring React, React Router, TypeScript, InversifyJS, IndexedDB, Vite, and Docker.

You can explore the source code, inspect the module layout, or clone the repository to follow along:

👉 GitHub Repository: github.com/schorts99/React-Clean-Architecture

📢 Up Next…

Get ready to re-examine how frontend applications should be built!

Coming up next: Part 1 — The Why: Why Architecture Matters on the Frontend. We will break down the mechanics of technical coupling, explain why framework-centric codebases fail over time, and introduce the core rule that keeps your core domain independent of external technologies. Stay tuned!