DEV Community: Jorge Castillo

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!