DEV Community: Dzmitry Harunou

Frontend Clean Architecture: Practical Insights and Pitfalls

Dzmitry Harunou — Tue, 01 Jul 2025 07:20:04 +0000

1. Implementation Is a UML Diagram
2. Hexagonal Architecture Terminology Can Obscure Clean Architecture
3. Codebase Evolution: The Overlooked Factor
4. Templates Undermine Agility
Conclusion

1. Implementation Is a UML Diagram

The Clean Architecture implementation is essentially a UML diagram for a specific application or type of applications. And this the most important insight I have gained over the years. This diagram bridges abstract principles and concrete code, defining application units, their relationships, boundaries, and dependencies.

So, the natural process of turning Clean Architecture into a codebase is as follows:

   +-----------------------------+
   |      Clean Architecture     |
   |          Principles         |
   +-----------------------------+
                  |
                  v
   +-----------------------------+
   |        UML Diagram          |
   |  (Units, Boundaries, Flow)  |
   +-----------------------------+
                  |
                  v
   +-----------------------------+
   |    Application Codebase     |
   |  (Concrete Implementation)  |
   +-----------------------------+

For a typical backend application written in Java, a well known Clean Architecture implementation has existed for many years:

However, this implementation does not directly apply to reactive frontend applications, which rely heavily on the observer pattern. In practice, attempting to adapt it to the frontend context often leads to unnecessary complexity, as it introduces excessive code solely for this adaptation, without providing real benefits. This is the main reason I often hear that Clean Architecture is painful for frontend applications.

Nevertheless, the principles of Clean Architecture are universal. An implementation tailored for a typical frontend application - with a store and API integration - can be slick, simple, and effective, as shown below:

This implementation can be used with any modern reactive frontend framework, such as React, Vue, Svelte, or Angular.

2. Hexagonal Architecture Terminology Can Obscure Clean Architecture

A huge source of confusion in projects built with Clean Architecture is the pervasive use of Hexagonal Architecture (Ports and Adapters) terminology throughout the codebase - often without explicit reason or explanation. While Clean Architecture and Hexagonal Architecture share similar goals and structural principles, they differ in terminology and emphasis.

When a developer joins a project structured with Clean Architecture, they may expect to see CA-specific layers and units — such as use cases, gateways, controllers, and presenters. However, in practice, much of the code may instead operate with Hexagonal terms like ports, adapters, and application/core layers, sometimes even following the naming and packaging conventions typical for Hexagonal systems.

This heavy reliance on Hexagonal terminology, without a clear mapping to Clean Architecture concepts, can make it difficult for developers to orient themselves, leading to confusion or even rejection of the architectural approach. The lack of explicit boundaries or documentation explaining how Hexagonal elements fit within the Clean Architecture structure only compounds the problem.

To improve clarity and onboarding, it is essential to acknowledge the use of Hexagonal Architecture and document how its concepts correspond to Clean Architecture elements — for example, mapping input ports to use cases, output ports to gateways, and adapters to controllers/presenters. This transparency helps maintain conceptual integrity while leveraging the strengths of both approaches.

3. Codebase Evolution: The Overlooked Factor

With a UML diagram that clearly defines the units of an application, developers have a blueprint for how the system should be structured. However, a common pitfall is to equate each unit in the diagram with a separate file in the codebase from the very beginning. This approach can lead to unnecessary fragmentation, boilerplate, and a proliferation of files that are difficult to navigate and maintain, especially in the early stages of a project.

Instead, when the architectural units are well understood, it is often more effective to inline related logic and keep the codebase simple at first. As the application grows, these units can be gradually extracted into their own files or modules as needed. This incremental factoring helps keep the codebase manageable and avoids premature abstraction, but requires discipline to refactor and extract units as complexity increases.

4. Templates Undermine Agility

Every project has unique requirements, and Clean Architecture encourages teams to make architectural decisions at the right time, based on actual needs rather than assumptions. Relying on templates can lead to premature abstraction, unnecessary complexity, and a false sense of security. Instead, it is better to use templates as learning tools or references, while allowing the application to grow organically in response to real-world challenges and changes.

Conclusion

Effective application of Clean Architecture requires a bridging implementation represented as a UML diagram. For frontend applications built with modern reactive frameworks, blindly following backend-oriented CA implementation or relying on templates can introduce unnecessary complexity and hinder agility. It is also important to understand the distinctions between Clean Architecture and Hexagonal Architecture, and to evolve the codebase organically - making decisions as real needs arise. Teams that understand these principles will avoid headaches throughout the entire application lifecycle.

Development Workflow in Clean Architecture for Frontend Applications

Dzmitry Harunou — Tue, 24 Jun 2025 08:31:03 +0000

This article shares an approach to the development workflow for frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/frontend-clean-architecture-exercise

Nice to know as well https://react.dev/learn/thinking-in-react

Step 1: Add View, Controller, and Presenter Units
Step 2: Add Entities Store Unit
Step 3: Add Gateway Unit Factory
Step 4: Connect the Presenter Unit to the Entities Store Unit
Step 5: Connect the Controller Unit to the Entities Store Unit and the Gateway Unit
Step 6: Add the In-Memory Gateway Unit
Step 7: Implement the External Resource Unit
Step 8: Add the Remote Gateway Unit
Conclusion

Building a frontend application that follows Clean Architecture is simple and straightforward. The general approach is to build units according to the Clean Architecture UML implementation, connecting them step by step to get the application up and running.

Let's examine the development workflow of a counter application in detail.

Before starting the implementation process, a developer typically has:

The application requirements:

The application should display a counter value.
The application should display the counter status based on its value: Positive, Negative, or Zero.
The application should allow incrementing the counter value.
The application should allow decrementing the counter value.
The application should allow resetting the counter value to 0.
The counter logic is performed on the server side.
The initial counter value is stored on the server side.
The initial counter value before the first request is 0.

A basic sketch of the user interface:

To build the application, we will use the Clean Architecture UML diagram for frontend applications.

Step 1: Add view, controller, and presenter units

The first step is to create the view unit, which is based on the user interface sketch. The view is the most straightforward unit to implement at this stage, as it focuses on presenting data and handling user interactions. If the backend is ready and API definitions are available, the external resource unit can be developed in parallel with the view. In this example, we assume the backend is not yet ready, so we start with the view.

Building the view unit helps to understand the application, while getting something (the view unit) done. For a simple counter application, we can use mocked presenter and controller units to provide test data and handlers, making it possible to test the view in the browser right away. These presenter and controller units can be easily extracted later as the application evolves.

function Counter() {
  // presenter unit implemented with constants (null presenter)
  // the presenter has assigned mocked data for testing in browser
  const countValue = 0;
  const countStatus = "Positive";

  // controller unit implemented with constants (null controller)
  // the controller has assigned mocked data for testing in browser
  const onIncrementButtonClick = () => {};
  const onDecrementButtonClick = () => {};
  const onResetButtonClick = () => {};

  // view unit
  return (
    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100 flex items-center justify-center p-4">
      <div className="bg-white rounded-2xl shadow-lg p-10 text-center max-w-sm w-full">
        {/* Header */}
        <h1 className="text-3xl font-bold text-gray-800 mb-8">Counter App</h1>

        {/* Counter Value Display */}
        <div className="bg-gray-50 rounded-xl py-8 mb-8 border-2 border-gray-200">
          <span className="text-6xl font-bold text-indigo-600">
            {countValue}
          </span>
        </div>

        {/* Control Buttons */}
        <div className="flex gap-4 justify-center mb-6">
          <button
            onClick={onDecrementButtonClick}
            className="w-16 h-16 bg-red-500 hover:bg-red-600 text-white text-2xl font-bold rounded-xl shadow-md hover:shadow-lg transform hover:-translate-y-0.5 transition-all duration-200"
          >
            -
          </button>

          <button
            onClick={onIncrementButtonClick}
            className="w-16 h-16 bg-green-500 hover:bg-green-600 text-white text-2xl font-bold rounded-xl shadow-md hover:shadow-lg transform hover:-translate-y-0.5 transition-all duration-200"
          >
            +
          </button>
        </div>

        {/* Reset Button */}
        <button
          onClick={onResetButtonClick}
          className="w-full py-3 px-6 bg-gray-600 hover:bg-gray-700 text-white font-semibold rounded-xl shadow-md hover:shadow-lg transform hover:-translate-y-0.5 transition-all duration-200"
        >
          Reset to Zero
        </button>

        {/* Count Status Display */}
        <p className="text-gray-500 text-sm mt-6">
          Status: <span className={`font-semibold`}>{countStatus}</span>
        </p>
      </div>
    </div>
  );
}

At this stage, the view unit is considered closed.

Step 2: Add entities store unit

Once the view unit is ready, we can analyze the controller and presenter interfaces and design the entities store unit. The entities store unit is responsible for storing the application's entities, which are minimal data structures that the application works with. In our case, the entities store unit will contain a single entity: the counter, with a count value and a setCount setter function.

const INITIAL_COUNT = 0;

function Counter() {
  // entities store unit (counter entity)
  const [count, setCount] = useState(INITIAL_COUNT);

  // presenter unit implemented with constants (null presenter)
  // the presenter has assigned mocked data for testing in browser
  const countValue = 0;
  const countStatus = "Positive";

  // controller unit implemented with constants (null controller)
  // the controller has assigned mocked data for testing in browser
  const onIncrementButtonClick = () => {};
  const onDecrementButtonClick = () => {};
  const onResetButtonClick = () => {};

  // view unit
  return (
    ...
  );
}

At this stage, the entities store unit is considered closed.

Step 3: Add gateway unit factory

Since the application connects to a backend service, the next step is to introduce the gateway unit factory. The gateway unit serves as an abstraction layer between the application and external resources.

In our counter application, the factory will provide a gateway unit with methods to access server-side logic. A simple gateway unit factory might look like this:

// gateway unit interface (yet empty)
interface CounterGateway {}

// gateway unit factory
const useCounterGateway = (): CounterGateway => {
  return {} as CounterGateway;
};

const INITIAL_COUNT = 0;

function Counter() {
  // entities store unit (counter entity)
  const [count, setCount] = useState(INITIAL_COUNT);

  // gateway unit
  const gateway = useCounterGateway();

  // presenter unit implemented with constants (null presenter)
  // the presenter has assigned mocked data for testing in browser
  const countValue = 0;
  const countStatus = "Positive";

  // controller unit implemented with constants (null controller)
  // the controller has assigned mocked data for testing in browser
  const onIncrementButtonClick = () => {};
  const onDecrementButtonClick = () => {};
  const onResetButtonClick = () => {};

  // view unit
  return (
    ...
  );
}

By introducing the gateway unit factory at this stage, you ensure that your application remains decoupled from the specifics of the backend implementation.

Step 4: Connect the presenter unit to the entities store unit

In this step, we connect the presenter unit property by property to the entities store unit. The presenter unit is responsible for transforming the raw data from the entities store into a format suitable for the view. This separation ensures that the view remains simple and focused only on presentation logic, while the presenter handles any necessary data formatting or status calculation.

For the counter application, the presenter unit will derive the countValue and countStatus from the counter entity. For example, the status can be determined based on whether the count is positive, negative, or zero.

Here is how you might connect the entities store to the presenter unit:

// gateway unit interface (yet empty)
interface CounterGateway {}

// gateway unit factory
const useCounterGateway = (): CounterGateway => {
  return {} as CounterGateway;
};

const INITIAL_COUNT = 0;

function Counter() {
  // entities store unit (counter entity)
  const [count, setCount] = useState(INITIAL_COUNT);

  // gateway unit
  const gateway = useCounterGateway();

  // presenter unit implemented with constants (null presenter)
  const countValue = count;
  const countStatus =
    count === 0 ? "Zero" : count > 0 ? "Positive" : "Negative";

  // controller unit implemented with constants (null controller)
  // the controller has assigned mocked data for testing in browser
  const onIncrementButtonClick = () => {};
  const onDecrementButtonClick = () => {};
  const onResetButtonClick = () => {};

  // view unit
  return (
    ...
  );
}

By connecting the entities store to the presenter unit, you ensure that any changes in the entities store unit are immediately reflected in the view.

At this stage, the presenter unit is considered closed.

Step 5: Connect the controller unit to the entities store unit and the gateway unit

In this step, we connect the controller unit to both the entities store unit and the gateway unit by implementing inlined use case interactors. The controller unit handles user interactions, updates the application's state, and communicates with the backend through the gateway. This process also helps to define the CounterGateway interface.

The example below demonstrates how the controller unit performs operations using pessimistic updates:

// gateway unit interface
interface CounterGateway {
  getCount: () => Promise<number>;
  incrementCount: () => Promise<number>;
  decrementCount: () => Promise<number>;
  resetCount: () => Promise<number>;
}

// gateway unit factory
const useCounterGateway = (): CounterGateway => {
  return {} as CounterGateway;
};

const INITIAL_COUNT = 0;

function Counter() {
  // entities store unit (counter entity)
  const [count, setCount] = useState(INITIAL_COUNT);

  // gateway unit
  const gateway = useCounterGateway();

  // presenter unit implemented with constants (null presenter)
  const countValue = count;
  const countStatus =
    count === 0 ? "Zero" : count > 0 ? "Positive" : "Negative";

  // controller unit implemented with constants (null controller)
  const onIncrementButtonClick = async () => {
    const remoteCount = await gateway.incrementCount();
    setCount(remoteCount);
  };
  const onDecrementButtonClick = async () => {
    const remoteCount = await gateway.decrementCount();
    setCount(remoteCount);
  };
  const onResetButtonClick = async () => {
    const remoteCount = await gateway.resetCount();
    setCount(remoteCount);
  };
  const onCounterMount = async () => {
    const remoteCount = await gateway.getCount();
    setCount(remoteCount);
  };

  // view unit lifecycle hook
  useEffect(() => {
    onCounterMount();
  }, []);

  // view unit
  return (
    ...
  );
}

At this stage, the controller unit is considered closed.

Step 6: Add the in-memory gateway unit

Until the backend is ready, you can implement an in-memory gateway unit to simulate server-side logic. This allows you to develop and test the application independently of the backend, ensuring the rest of your architecture works as expected.

The in-memory gateway unit should implement the CounterGateway interface and manage the counter value in local memory. Each method will update or return the value as if it were communicating with a real server.

Here is an example of an in-memory gateway unit implementation:

// FILE: types.ts
export interface CounterGateway {
  getCount: () => Promise<number>;
  incrementCount: () => Promise<number>;
  decrementCount: () => Promise<number>;
  resetCount: () => Promise<number>;
}

// FILE: gateways.ts
let count = 5;

// counter gateway unit (in-memory)
export const inMemoryCounterGateway: CounterGateway = {
  getCount: async () => {
    return count;
  },
  incrementCount: async () => {
    count += 1;
    return count;
  },
  decrementCount: async () => {
    count -= 1;
    return count;
  },
  resetCount: async () => {
    count = 0;
    return count;
  },
};

// FILE: hooks.ts
// gateway unit factory
export const useCounterGateway = (): CounterGateway => {
  return inMemoryCounterGateway;
};

Implementing the in-memory gateway unit and updating the useCounterGateway hook did not require any changes to the Counter component. This demonstrates how Clean Architecture allows you to swap gateway implementations without affecting the application core.

At this stage, the in-memory gateway unit is considered closed.

Step 7: Implement the external resource unit

Once the backend service is ready, we implement the external resource unit, which represents the counter backend service in our application. The external resource unit encapsulates all HTTP requests related to the service, providing a clear interface for fetching and updating the counter value on the server.

The counter external resource unit could look like this:

// FILE: api.ts
interface ApiCountDto {
  value: number;
}

// counter external resource unit
export const CounterApi = {
  async getCount(): Promise<ApiCountDto> {
    const response = await fetch("/api/counter");
    if (!response.ok) {
      throw new Error("Failed to fetch count");
    }
    return response.json();
  },

  async incrementCount(): Promise<ApiCountDto> {
    const response = await fetch("/api/counter/increment", { method: "POST" });
    if (!response.ok) {
      throw new Error("Failed to increment count");
    }
    return response.json();
  },

  async decrementCount(): Promise<ApiCountDto> {
    const response = await fetch("/api/counter/decrement", { method: "POST" });
    if (!response.ok) {
      throw new Error("Failed to decrement count");
    }
    return response.json();
  },

  async resetCount(): Promise<ApiCountDto> {
    const response = await fetch("/api/counter/reset", { method: "POST" });
    if (!response.ok) {
      throw new Error("Failed to reset count");
    }
    return response.json();
  },
};

At this stage, the external resource unit is considered closed.

Step 8: Add the remote gateway unit

In this step, we add the remote gateway unit, which acts as an adapter between the application's core logic and the external resource unit (API). The remote gateway implements the CounterGateway interface and delegates all operations to the CounterApi methods, converting the API responses into the format expected by the rest of the application.

The code also shows how the useCounterGateway hook can dynamically select between the in-memory gateway (for development) and the remote gateway (for production).

// FILE: gateways.ts
// counter gateway unit (remote)
export const remoteCounterGateway: CounterGateway = {
  getCount: async () => {
    const response = await CounterApi.getCount();
    return response.value;
  },
  incrementCount: async () => {
    const response = await CounterApi.incrementCount();
    return response.value;
  },
  decrementCount: async () => {
    const response = await CounterApi.decrementCount();
    return response.value;
  },
  resetCount: async () => {
    const response = await CounterApi.resetCount();
    return response.value;
  },
};

// FILE: hooks.ts
// gateway unit factory
export const useCounterGateway = (): CounterGateway => {
  if (import.meta.env.DEV) {
    return inMemoryCounterGateway;
  }
  return remoteCounterGateway;
};

Implementing the remote gateway unit and updating the useCounterGateway hook did not require any changes to the Counter component. This demonstrates how Clean Architecture allows you to swap gateway implementations without affecting the application core.

At this stage, the remote gateway unit is considered closed and the counter app is ready for production.

Conclusion

This workflow shows how Clean Architecture enables you to incrementally build frontend applications or features. It improves code quality, streamlines collaboration, supports parallel work, and simplifies long-term maintenance.

Testing in Clean Architecture for Frontend Applications

Dzmitry Harunou — Mon, 16 Jun 2025 09:55:48 +0000

This article shares approach to the unit, integration and end-to-end tests in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Unit Tests
Integration Tests
End-to-End (E2E) Tests
Conclusion

In practice, tests written for applications that follow clean architecture offer the following benefits:

Clear Unit Visibility: Clean architecture makes individual units easy to identify, each with a well-defined interface.
Test Stability Gradient: Tests reflect the application's stability pattern: tests for the application core are the most stable, while those for the driver's layer are less stable but remain well-structured.
Effective Mocking: Dependencies can be easily mocked at layer boundaries, enabling true unit testing without external dependencies.

To achieve these benefits and provide comprehensive coverage, clean architecture applications leverage three complementary testing approaches:

Unit tests: Test individual units in isolation.
Integration tests: Verify the interaction between different units.
End-to-end (E2E) tests: Test complete user workflows and system behavior from the user's perspective.

Unit Tests

Unit tests are designed to test individual units or functions in isolation. They focus on the smallest parts of the application, ensuring that each unit works correctly on its own.

The example below demonstrates a unit test for a view unit with mocked dependencies. The test only needs to change if the view unit itself changes.

// Orders.test.tsx
// Mock dependencies for the Orders component and its hooks
vi.mock("./hooks/useController");
vi.mock("./hooks/usePresenter");
// Provide a simple mock Order component for rendering
vi.mock("../Order/Order", () => ({
  Order: (props: { orderId: OrderEntityId }) => (
    <div data-testid={`order-${props.orderId}`}>Order {props.orderId}</div>
  ),
}));

describe(`Orders`, () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it("renders multiple orders", () => {
    const orderIds = ["1", "2", "3"] as OrderEntityId[];
    // Mock the presenter factory to provide test data
    vi.mocked(usePresenter).mockReturnValue({
      totalItemsQuantity: 5,
      isLoading: false,
      orderIds,
    });
    // Mock the controller factory to provide controller methods
    vi.mocked(useController).mockReturnValue({
      moduleDestroyed: vi.fn(),
    });

    render(<Orders />);

    expect(screen.getByTestId(totalItemQuantityTestId)).toHaveTextContent("5");
    expect(screen.getByText("Status: pending")).toBeInTheDocument();
    // Check that each order is rendered
    orderIds.forEach((id) => {
      expect(screen.getByTestId(`order-${id}`)).toBeInTheDocument();
    });
  });

  // ...other tests for different scenarios
});

Another approach is to extract the core logic into a pure function or a set of pure functions. For example, let's consider testing a selector unit where the selection logic has been extracted into a pure function.

// useVisibleItemIdsSelector.ts
// selector unit
export const useVisibleItemIdsSelector = (params: { orderId: string }): string[] => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  return select(order, visibleItemsIds);
};

// extracted select (core) logic
type OrderEntityForSelect = { itemEntities: Array<{ id: string }>; } | undefined;

export const select = (order: OrderEntityForSelect, visibleItemsIds: string[]): string[] => {
  return (
    order?.itemEntities
      .filter((itemId) => visibleItemsIds.includes(itemId))
      .map((itemEntity) => itemEntity.id) ?? []
  );
};

// useVisibleItemIdsSelector.test.ts
describe("select", () => {
  it("returns only visible item ids present in the order", () => {
    const order = {
      itemEntities: [
        { id: "item-1" },
        { id: "item-2" },
        { id: "item-3" },
      ],
    };
    const visibleItemsIds = ["item-2", "item-3", "item-4"];
    const result = select(order, visibleItemsIds);
    expect(result).toEqual(["item-2", "item-3"]);
  });

  // ...other tests for different scenarios
});

Integration Tests

Integration tests verify how multiple units work together as a group.

The following example demonstrates an integration test of the application core, specifically for a selector unit. This test does not depend on any external resources and remains stable as long as the application core remains unchanged.

// useTotalItemsQuantitySelector.test.tsx
interface LocalTestContext {
  Fixture: FC<PropsWithChildren<unknown>>;
  gateway: Mocked<OrdersGateway>;
  orders: OrderEntity[];
}

describe(`useTotalItemsQuantitySelector`, () => {
  beforeEach<LocalTestContext>((context) => {
    vi.useFakeTimers();

    resetOrderEntitiesFactories();
    const fakeOrderEntities = makeOrderEntities();

    // Fixture component provides the necessary context
    const { Fixture } = makeComponentFixture();
    context.Fixture = Fixture;
    // mockUseOrdersGateway mocks the orders gateway factory and returns
    // a mock instance, which is used in the test to supply test data
    context.gateway = mockUseOrdersGateway();
    context.orders = fakeOrderEntities;
  });

  afterEach(() => {
    vi.restoreAllMocks();
    vi.useRealTimers();
  });

  it<LocalTestContext>("returns total quantity of items in the order ", async (context) => {
    // The 'getOrders' mock returns data in the application core data format.
    // Regardless of which external resource the gateway connects to, this test
    // remains unchanged. It only changes if the gateway or selector interface
    // changes.
    context.gateway.getOrders.mockResolvedValueOnce(context.orders);

    const { result } = renderHook(() => useTotalItemsQuantitySelector(), {
      wrapper: context.Fixture,
    });

    await vi.runAllTimersAsync();

    // Assert that the selector returns the expected total quantity
    expect(result.current).toBe(1825);
  });

  // ...other tests for different scenarios
});

Integration tests are also useful for verifying how gateways interact with external resources. These tests are a good place to use libraries that mock HTTP requests, such as MSW (Mock Service Worker).

// RemoteOrdersGateway.test.ts
const server = setupServer();

interface LocalTestContext {
  gateway: RemoteOrdersGateway;
}

describe(`RemoteOrdersGateway`, () => {
  beforeAll(() => {
    server.listen({
      onUnhandledRequest: "error",
    });
  });
  beforeEach<LocalTestContext>((context) => {
    apiOrderDtoFactory.resetCount();
    context.gateway = RemoteOrdersGateway.make();
  });
  afterAll(() => {
    server.close();
  });
  describe("getOrders", () => {
    it<LocalTestContext>("fetches order entities", async (context) => {
      // Prepare test data that will be received by the orders external resource
      // unit as a http response
      const apiOrdersDto = apiOrderDtoFactory.list({ count: 1 });

      // Define the expected result in the application core format as returned
      // by the gateway
      const expected: OrderEntity[] = [
        {
          id: makeOrderEntityId("1"),
          userId: "75",
          itemEntities: [
            { id: makeItemEntityId("1"), productId: "59", quantity: 75 },
            { id: makeItemEntityId("2"), productId: "17", quantity: 50 },
            { id: makeItemEntityId("3"), productId: "93", quantity: 60 },
          ],
        },
      ];

      // Mock the HTTP GET request for orders external resource
      server.use(
        http.get(ordersApiUrl, () => HttpResponse.json(apiOrdersDto), {
          once: true,
        }),
      );
      // Call the gateway method and assert the result
      const result = await context.gateway.getOrders();
      expect(result).toEqual(expected);
    });
  });
});

End-to-End (E2E) Tests

End-to-end tests verify the integrity and flow of the entire application, from the view unit up to the external resource unit. The tests can share types and factories defined for external resources, as well as view identifiers (for example, test-ids) from the view units. End-to-end tests are less stable, as they depend on units, which are not part of the application core and may change more frequently.

Conclusion

Testing frontend applications that follow Clean Architecture principles can be structured and maintainable by clearly separating unit, integration, and end-to-end tests. Unit tests verify the correctness of isolated units and pure functions, integration tests check how units collaborate (for example, the application core), and end-to-end tests validate the application's behavior as a whole. Tests follow the application's stability gradient: the more stable a unit is, the more stable its corresponding tests will be.

External Resource Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Mon, 09 Jun 2025 10:07:00 +0000

This article shares the concept and implementation of the external resource unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

External Resource Implementation
Q&A
- How should the external resource unit be tested?
- Where should the external resource unit be placed?
- Can the external resource unit use entity types instead of declaring its own?
Conclusion

The external resource unit represents a specific external data source or service that a frontend application interacts with.

External Resource Implementation

The implementation of this unit relies solely on the interface of the actual external resource.

All development focus is on the real external resource interface and its representation within the application.

By the end of the external resource unit implementation, developers should be able to understand the available remote API based on the implemented unit, without needing to consult backend documentation directly.

Let's look at an example of an external resource representing an Orders API provided by a backend service.

The first step is to obtain the external resource declaration in any API description format or documentation. In this case, we use OpenAPI:

openapi: 3.0.0
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: /api
paths:
  /orders:
    get:
      summary: Get all orders
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/order'
  /orders/{id}:
    get:
      summary: Get order by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
    put:
      summary: Update order by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/order'
      responses:
        '204':
          description: No content
    delete:
      summary: Delete order by ID
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content
components:
  schemas:
    order:
      type: object
      properties:
        id:
          type: string
        userId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/item'
      required:
        - id
        - userId
        - items
    item:
      type: object
      properties:
        id:
          type: string
        productId:
          type: string
        quantity:
          type: integer
      required:
        - id
        - productId
        - quantity

Next, we implement the external resource unit in the frontend application, beginning with types and interfaces. These types can be generated automatically by a specialized code generator based on the OpenAPI declaration above or a similar tool.

export interface ApiOrderDto {
  id: string;
  userId: string;
  items: ApiOrderItemDto[];
}

export interface ApiOrderItemDto {
  id: string;
  productId: string;
  quantity: number;
}

Finally, we implement the external resource unit as shown below, with methods that directly reflect the API operations defined in the API service declaration.

const baseUrl = import.meta.env.BASE_URL;

export class OrdersApi {
  static make(): OrdersApi {
    return new OrdersApi(HttpClient.make());
  }

  private ordersApiUrl = `${baseUrl}api/orders`;

  constructor(private readonly httpClient: ApiHttpClient) {}

  async getOrders(): Promise<ApiOrderDto[]> {
    const request = new Request(new URL(this.ordersApiUrl), {
      method: "GET",
    });
    const response = await this.httpClient.request(request);
    return response.json();
  }

  async getOrder(id: string): Promise<ApiOrderDto> {
    const request = new Request(new URL(`${this.ordersApiUrl}/${id}`), {
      method: "GET",
    });
    const response = await this.httpClient.request(request);
    return response.json();
  }

  async updateOrder(id: string, order: Partial<ApiOrderDto>): Promise<void> {
    const request = new Request(new URL(`${this.ordersApiUrl}/${id}`), {
      method: "PUT",
      body: JSON.stringify(order),
    });
    await this.httpClient.request(request);
  }

  async deleteOrder(id: string): Promise<void> {
    const request = new Request(new URL(`${this.ordersApiUrl}/${id}`), {
      method: "DELETE",
    });
    await this.httpClient.request(request);
  }
}

At this stage, the external resource unit is ready to be used in the application.

Q&A

How should the external resource unit be tested?

In practice, the best way to test it is through integration tests with the gateway unit, using libraries like MSW. An example integration test is available here:
RemoteOrdersGateway.spec.ts

Where should the external resource unit be placed?

The unit should be placed in a dedicated api directory.

Can the external resource unit use entity types instead of declaring its own?

It is generally recommended that the external resource unit declare its own types that directly reflect the structure and types of the external API. The external resource unit and the application core exist independently within the application; they do not know about each other and do not share anything between them. The only component that connects the core and the external resource is the gateway unit.

Conclusion

The external resource unit represents a specific external resource or service in a frontend application. By encapsulating API details and aligning with backend contracts, it enables seamless integration and enhances the developer experience.

Gateway Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Mon, 02 Jun 2025 14:43:09 +0000

This article shares the concept and implementation of the gateway unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Gateway Implementation
Q&A
- How should the gateway unit be tested?
- Where should gateways be placed?
- Is a factory function required for the gateway unit?
- Should the gateway unit always be implemented as a class?
- The gateway unit depends on entities store unit. Why?
- What can I do if an external resource is not yet defined?
Conclusion

The gateway unit decouples the application core from external data sources and services. It manages interactions with external systems like APIs, browser storage, or Web Workers, handling data mapping, error isolation, and caching.

Gateway Implementation

The gateway implements an interface defined by the application core. The primary development context focuses on the interface implementation.

Let's look into an example of a gateway that interacts with an external API.

The gateway interface starts out empty or minimal. As the application core defines new requirements for interacting with the outside world, the interface is extended with new methods. This process continues until the interface fully represents all the external interactions needed by the application core. Interface methods use primitive types or DTOs as parameters and return types.

export interface ItemEntity {
  id: string;
  productId: string;
  quantity: number;
}

export interface OrderEntity {
  id: string;
  userId: string;
  items: ItemEntity[];
}

// Interface defined by the application core
export interface OrdersGateway {
  getOrders(): Promise<OrderEntity[]>;
  deleteOrder(orderId: string): Promise<void>;
  deleteItem(orderId: string, itemId: string): Promise<void>;
}

Next, when the external resource units are sufficiently defined, the gateway implementation that connects the application to external resources might look as follows:

// External resource DTO to application entity mapper
export function toOrderEntity(dto: ApiOrderDto): OrderEntity {
  return {
    id: makeOrderEntityId(dto.id),
    userId: dto.userId,
    items: dto.items.map(toItemEntity),
  };
}

// External resource DTO to application entity mapper
export function toItemEntity(dto: ApiOrderItemDto): ItemEntity {
  return {
    id: makeItemEntityId(dto.id),
    productId: dto.productId,
    quantity: dto.quantity,
  };
}

// RemoteOrdersGateway connects application core to the external resource
export class RemoteOrdersGateway implements OrdersGateway {
  static make(): RemoteOrdersGateway {
    return new RemoteOrdersGateway(OrdersResourceApi.make());
  }

  constructor(private ordersResourceApi: OrdersResourceApi) {}

  async getOrders(): Promise<OrderEntity[]> {
    const ordersDto = await this.ordersResourceApi.getOrders();
    return ordersDto.map(toOrderEntity);
  }

  deleteOrder(orderId: string): Promise<void> {
    return this.ordersResourceApi.deleteOrder(orderId);
  }

  async deleteItem(orderId: string, itemId: string): Promise<void> {
    // The gateway implements the `deleteItem` method, required by the
    // application core, using the available external resource API operations,
    // `getOrder` and `updateOrder`, because the API does not provide a direct
    // deleteItem endpoint. The approach can be revised and improved in future
    // API updates without impacting the application core.
    const orderDto = await this.ordersResourceApi.getOrder(orderId);
    const updatedOrder: ApiOrderDto = {
      ...orderDto,
      items: orderDto.items.filter((item) => item.id !== itemId),
    };
    await this.ordersResourceApi.updateOrder(orderId, updatedOrder);
  }
}

Clients of the gateway should rely exclusively on the gateway interface rather than on a concrete implementation. This approach enables seamless replacement of gateway implementations and simplifies mocking for development and integration testing. To achieve this, clients can use a factory function that returns an instance of a gateway conforming to the gateway interface.

// useOrdersGateway.ts
export const useOrdersGateway = (): OrdersGateway => {
  return RemoteOrdersGateway.make();
};

// useDeleteOrderUseCase.ts
export const useDeleteOrderUseCase = (): UseCase<{ orderId: OrderEntityId }> => {
  const gateway = useOrdersGateway();
  const deleteOrderTransaction = useDeleteOrderTransaction(params);
  const displayHttpErrorTransaction = useDisplayHttpErrorTransaction();

  const execute = async (params: { orderId: OrderEntityId }) => {
    try {
      await gateway.deleteOrder(params);
      deleteOrderTransaction(params);
    } catch (error: unknown) {
      if (isHttpError(error)) {
        displayHttpErrorTransaction(error);
        return;
      }
      throw new Error("Unknown error");
    }
  };

  return { execute };
};

At this stage, the gateway implementation is ready to be used.

Q&A

How should the gateway unit be tested?

The gateway unit can be tested both integrated with dependent units and in isolation using mocks. An example integration test is available here: RemoteOrdersGateway.spec.ts

Where should gateways be placed?

Gateways are suggested to be placed in a dedicated gateways directory.

Is a factory function required for the gateway unit?

To allow the application core to depend on gateway interfaces rather than their concrete implementations, you can use a factory function, dependency injection, or a service locator. A factory function is the simplest approach, but more advanced patterns can be used if your project requires them.

Should the gateway unit always be implemented as a class?

Gateways can be implemented either as classes or as sets of functions, depending on team and application requirements. An example using functions:

const getOrders: OrdersGateway["getOrders"] = async () => {
  const api = OrdersResourceApi.make();
  const ordersDto = await api.getOrders();
  return ordersDto.map(toOrderEntity);
};

const deleteOrder: OrdersGateway["deleteOrder"] = (orderId) => {
  const api = OrdersResourceApi.make();
  return api.deleteOrder(orderId);
};

const deleteItem: OrdersGateway["deleteItem"] = async (orderId, itemId) => {
  const api = OrdersResourceApi.make();
  const orderDto = await api.getOrder(orderId);
  const updatedOrder: ApiOrderDto = {
    ...orderDto,
    items: orderDto.items.filter((item) => item.id !== itemId),
  };
  await api.updateOrder(orderId, updatedOrder);
};

const gateway: OrdersGateway = {
  getOrders,
  deleteOrder,
  deleteItem,
};

export const makeRemoteOrdersGateway = () => gateway;

The gateway unit depends on entities store unit. Why?

Gateways may depend on entities store units to read the current application state and adjust their behavior accordingly. For example, a gateway might need to decide which external resource to use based on the current state. In practice, gateway access to the store should be limited and mostly read-only. However, in some cases, allowing the gateway to perform write operations can be useful.

It's important to note that the gateway should not take on the responsibilities of use case interactor unit. The gateway's main role is to interact with external systems, not to implement business logic or coordinate application workflows.

What can I do if an external resource is not yet defined?

If the external resource is not yet defined or available, you can still proceed with application core and gateway development by using a stub or mock implementation of the gateway interface.

For example, you can implement a LocalOrdersGateway that fulfills the OrdersGateway interface and returns mock data, which can be used in development and testing environments. This will not somehow affect the application core implementation.

// LocalOrdersGateway.ts
// LocalOrdersGateway is a mock implementation of OrdersGateway
export class LocalOrdersGateway implements OrdersGateway {
  static make(): LocalOrdersGateway {
    const fakeOrders = ordersFactory.list({ count: 10 });
    return new LocalOrdersGateway(fakeOrders);
  }

  constructor(private orders: OrderEntity[] = []) {}

  getOrders(): Promise<OrderEntity[]> {
    return Promise.resolve([...this.orders]);
  }

  deleteOrder(orderId: string): Promise<void> {
    this.orders = this.orders.filter((order) => order.id !== orderId);
    return Promise.resolve();
  }

  deleteItem(orderId: string, itemId: string): Promise<void> {
    this.orders = this.orders.map((order) =>
      order.id === orderId
        ? {
            ...order,
            items: order.items.filter((item) => item.id !== itemId),
          }
        : order
    );
    return Promise.resolve();
  }
}

// useOrdersGateway.ts
export const useOrdersGateway = (): OrdersGateway => {
  if (process.env.NODE_ENV === "development") {
    // Use LocalOrdersGateway in development for faster iteration
    return LocalOrdersGateway.make();
  }
  return RemoteOrdersGateway.make();
};

This strategy improves development speed, enables parallel work between frontend and backend teams.

Conclusion

Gateway interfaces effectively decouple application core from specific data sources and services, significantly improving flexibility, maintainability, and testability. This approach ensures stable integration tests and protects core logic from external dependency changes.

Effect Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Tue, 20 May 2025 07:38:00 +0000

This article shares the concept and implementation of the Effect unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Effect Implementation
- Inline Effect Implementation
- Extracted Effect Implementation
Q&A
- How should an Effect unit be tested?
- Where should Effects be placed?
- Can Effects be nested?
- Can multiple Effects be used simultaneously?
Conclusion

The Effect unit encapsulates logic interacting with external resources through gateways. It manages side effects, asynchronous operations, and request orchestration.

Effect units handle cross-gateway requests, data fetching, sending processes, and sharing fetch logic across multiple use case interactors.

Effect Implementation

An Effect implements an interface provided by a consumer (use case interactor). This interface could represent a function required by use case or more complex one, which is use globally across application.

Effect implementations evolve from an inline form within consumers to extracted units:

 ---------------        ------------------
| inline effect | ---> | extracted effect |
 ---------------        ------------------

Initially, effects are implemented inline, focused on fetching data, sending requests, and orchestrating interactions.

Inline Effect Implementation

Consider a use case interactor that initializes an entities store upon application startup, requiring orders and users data:

export const useInitializeApplicationUseCase = (): { execute: () => Promise<void> } => {
  const usersGateway = useUsersGateway();
  const ordersGateway = useOrdersGateway();

  const execute = async () => {
    // inline effect
    const users = await usersGateway.getUsers();
    const orders = await ordersGateway.getOrders();

    setUsersAndOrdersTransaction({ users, orders });
  };

  return { execute };
};

Extracted Effect Implementation

The inline implementation can be extracted into a reusable effect unit:

// File: getUsersAndOrdersEffect.ts
export const getUsersAndOrdersEffect = async () => {
  const usersGateway = useUsersGateway();
  const ordersGateway = useOrdersGateway();

  const users = await usersGateway.getUsers();
  const orders = await ordersGateway.getOrders();

  return { users, orders };
};

// File: useInitializeApplicationUseCase.ts
export const useInitializeApplicationUseCase = (): { execute: () => Promise<void> } => {
  const execute = async () => {
    const { users, orders } = await getUsersAndOrdersEffect();

    setUsersAndOrdersTransaction({ users, orders });
  };

  return { execute };
};

Extracted effects encapsulate logic completely, allowing internal modifications such as parallel requests without affecting consumers:

// File: getUsersAndOrdersEffect.ts
export const getUsersAndOrdersEffect = async () => {
  const usersGateway = useUsersGateway();
  const ordersGateway = useOrdersGateway();

  // Fetch users and orders in parallel
  const [users, orders] = await Promise.all([
    usersGateway.getUsers(),
    ordersGateway.getOrders(),
  ]);

  return { users, orders };
};

// File: useInitializeApplicationUseCase.ts
export const useInitializeApplicationUseCase = (): { execute: () => Promise<void> } => {
  const execute = async () => {
    const { users, orders } = await getUsersAndOrdersEffect();

    setUsersAndOrdersTransaction({ users, orders });
  };

  return { execute };
};

Effect names should clearly indicate their function and end with the suffix Effect.

Q&A

How should an Effect unit be tested?

Effect units can be tested in integration with their dependent units or in isolation using mocks.

Where should Effects be placed?

Effects are suggested to be placed in a dedicated effects directory.

Can Effects be nested?

Yes, Effects can be nested. However, nesting may complicate reasoning and testing, so use with care.

Can multiple Effects be used simultaneously?

Yes, using multiple effects simultaneously is common and practical.

Conclusion

Effect units effectively manage asynchronous operations and coordinate cross-gateway interactions. Begin with inline implementations and extract effects only as needed, maintaining architecture flexibility as application complexity grows.

Entities Store Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Thu, 15 May 2025 12:06:50 +0000

This article shares the concept and implementation of the entities store unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Store Implementation
Inline Entities Store Implementation
Extracted Entities Store Implementation
Q&A
- How to test the store?
- Should domain and presentation stores be kept separate?
Conclusion

The store unit maintains a collection of enterprise business entities and/or application business entities and their states. An entity can be an object with methods, or it can be a set of data structures and functions. It depends on the the way the store implemented and external libraries used.

Store Implementation

Entities store implementation starts from modeling entities, which should keep minimal data needed to make the application working properly. Basis for the entities store models could be view unit's public interfaces, business logic requirements, etc. The important rule is that the entities store should serve the frontend application purpose and not more.

Particular store implementation depends on a library used (React useState, useReducer, Redux, Mobx, Zustand, etc.).

The unit has two possible implementation types: inline and extracted. In practice, the unit evolves in the following way:

 --------------        -----------------
| inline store | ---> | extracted store |
 --------------        -----------------

Additionally, both inline and extracted stores can be split into domain and presentation stores. The domain store manages enterprise business entities, while the presentation store handles application business entities.

All development context is focused on modeling entities.

Inline entities store implementation

Let's look at a basic example, where we have already implemented inlined business and application entities stores, use case, presenter, controller and view units.

interface ItemEntity {
  id: string;
  productId: string;
  quantity: number;
}

interface OrderEntity {
  id: string;
  userId: string;
  items: ItemEntity[];
}

export const TotalOrdersAndItemsAmount: FC = () => {
  // inline enterprise business entities store
  const [orders, setOrders] = useState<OrderEntity[]>([]);
  // inline application business entity store
  const [isLoading, setIsLoading] = useState(false);

  const ordersGateway = useOrdersGateway();

  // inline use case interactor
  const loadOrders = async () => {
    setIsLoading(true);
    const orders = await ordersGateway.getOrders();
    setOrders(orders);
    setIsLoading(false);
  };

  // inline presenter
  const totalOrdersAmount = orders.length;

  const totalItemsAmount = orders.reduce((acc, order) => acc + order.items.length, 0);

  // inline controller
  const refreshButtonClicked = () => {
    loadOrders();
  };

  const componentMounted = () => {
    loadOrders();
  };

  // lifecycle hook
  useEffect(() => {
    componentMounted();
  }, []);

  // view
  return (
    <>
      <button onClick={refreshButtonClicked}>Refresh</button>
      {isLoading && <div>Loading....</div>}
      <div>Total orders Amount: {totalOrdersAmount}</div>
      <div>Total items Amount: {totalItemsAmount}</div>
    </>
  );
};

Extracted entities store implementation

When the state needs to be shared across multiple components, extracting it into a centralized store is suggested. Various approaches and libraries can be used to manage the extracted state. The following example demonstrates an implementation using the Zustand state manager.

// File: OrdersStore.tx
export interface ItemEntity {
  id: string;
  productId: string;
  quantity: number;
}

export interface OrderEntity {
  id: string;
  userId: string;
  items: ItemEntity[];
}

type OrdersStore = {
  orders: OrderEntity[];
  setOrders: (orders: OrderEntity[]) => void;
};

export const useOrdersStore = create<OrdersStore>((set) => ({
  orders: [],
  setOrders: (orders) => set({ orders }),
}));

// File: TotalOrdersAndItemsAmount.tsx
export const TotalOrdersAndItemsAmount: FC = () => {
  // extracted enterprise business entities store
  const orders = useOrdersStore((state) => state.orders);
  const setOrders = useOrdersStore((state) => state.setOrders);

  // inline application business entity store
  const [isLoading, setIsLoading] = useState(false);

  const ordersGateway = useOrdersGateway();

  // inline use case interactor
  const loadOrders = async () => {
    setIsLoading(true);
    const orders = await ordersGateway.getOrders();
    setOrders(orders);
    setIsLoading(false);
  };

  // inline presenter
  const totalOrdersAmount = orders.length;

  const totalItemsAmount = orders.reduce((acc, order) => acc + order.items.length, 0);

  // inline controller
  const refreshButtonClicked = () => {
    loadOrders();
  };

  const componentMounted = () => {
    loadOrders();
  };

  // lifecycle hook
  useEffect(() => {
    componentMounted();
  }, []);

  // view
  return (
    <>
      <button onClick={refreshButtonClicked}>Refresh</button>
      {isLoading && <div>Loading....</div>}
      <div>Total orders Amount: {totalOrdersAmount}</div>
      <div>Total items Amount: {totalItemsAmount}</div>
    </>
  );
};

Q&A?

How to test the store?

The entities store unit can be tested both in integration with other units and in isolation, following the guidelines provided by the store library provider.

Should domain and presentation stores be kept separate?

As practice shows, it is worth splitting them. In the beginning, the values can live together, but as the store grows, it is recommended to separate these types of entities. Keeping enterprise business entities separate makes it easier to observe and understand the core data necessary for the application to work.

Conclusion

Entities store unit helps organize and manage both enterprise (domain) and application (presentation) business entities, supporting a clear separation of concerns. Starting with an inline store is often sufficient for simple cases, but as the application grows, extracting the store and splitting domain and presentation entities becomes beneficial. Following these architectural principles leads to robust frontend applications.

Transaction Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Tue, 15 Apr 2025 08:06:07 +0000

This article shares the concept and implementation of the transaction unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Transaction Implementation
- Inline Transaction Implementation
- Extracted Transaction Implementation
Q&A
- How to test the transactions?
- Where to place it?
- What is the transaction interface and do I need a specific one?
- Can I use a transaction inside another transaction?
- Can I use multiple transactions at once?
Conclusion

The transaction unit is responsible for transitioning a store between two valid states while ensuring that business rules are maintained. It encapsulates the logic required to perform these state transitions, ensuring the application remains consistent.

The transaction unit is crucial for making cross-entity transitions and controlling view rerendering. Additionally, it enables sharing transition logic between different usecases.

The transaction unit does not return any data because, according to the unified data flow principle, data flows from the transaction unit into the view unit through entities and selectors.

Transaction Implementation

The transaction implements an interface provided by a consumer (usecase). The interface could be just a function which the usecase should provide or a more complex one used globally across the application.

The unit has two possible implementation types: inline and extracted. In practice, the unit evolves in the following way:

 --------------------        -----------------------
| inline transaction | ---> | extracted transaction |
 --------------------        -----------------------

Any transaction implementation starts from a simple inline function in a consumer.

All development context is focused on the store transitioning logic.

Inline Transaction Implementation

Let's look at a basic example, where we have already implemented the view, controller and partially inline usecase.

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked(id: string): Promise<void>;
}

const useController = (params: { orderId: string }): Controller => {
  const resource = useOrdersResourceSelector();
  const { mutateAsync: deleteOrder } = useMutation({ ...useDeleteOrderOptions(resource) });

  const deleteOrderButtonClicked = async () => {
    // inline usecase without transaction
    await deleteOrder({ id: params.orderId });
  };

  return { deleteOrderButtonClicked };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <>
      <button onClick={controller.deleteOrderButtonClicked}>Delete</button>
      <div style={{ padding: "5px" }}>
        {presenter.itemIds.map((itemId) => (
          <OrderItem key={itemId} itemId={itemId} />
        ))}
      </div>
    </>
  );
};

In the usecase, we need to clean the filter of items and reset the sort order when the order is deleted. Observing the codebase, we found that filter values are stored in one store and sort order in another. The transaction implementation will look like this:

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked(id: string): Promise<void>;
}

const useController = (params: { orderId: string }): Controller => {
  const setFilterById = useItemsFilterStore((state) => state.setFilterById);
  const setSortOrder = useOrdersSortOrderStore((state) => state.setSortOrder);

  const resource = useOrdersResourceSelector();
  const { mutateAsync: deleteOrder } = useMutation({ ...useDeleteOrderOptions(resource) });

  const deleteOrderButtonClicked = async () => {
    // inline usecase with transaction
    await deleteOrder({ id: params.orderId });

    // inline transaction performs pessimistic update
    setFilterById(null);
    setSortOrder('asc');
  };

  return { deleteOrderButtonClicked };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <>
      <button onClick={controller.deleteOrderButtonClicked}>Delete</button>
      <div style={{ padding: "5px" }}>
        {presenter.itemIds.map((itemId) => (
          <OrderItem key={itemId} itemId={itemId} />
        ))}
      </div>
    </>
  );
};

Extracted Transaction Implementation

The final step is to observe the codebase for the need of transaction extraction and reuse. The extraction happens if any other consumer unit already has the same logic implemented or the transaction becomes more complex. In this case, the inline transaction evolves to an extracted one.

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked(id: string): Promise<void>;
}

// extracted transaction
const useResetSortOrderAndFilterTransaction = (): { commit: () => void } => {
  const setFilterById = useItemsFilterStore((state) => state.setFilterById);
  const setSortOrder = useOrdersSortOrderStore((state) => state.setSortOrder);
  return {
    commit: () => {
      setFilterById(null);
      setSortOrder('asc');
    },
  };
};

const useController = (params: { orderId: string }): Controller => {
  const resource = useOrdersResourceSelector();
  const { mutateAsync: deleteOrder } = useMutation({ ...useDeleteOrderOptions(resource) });
  const { commit: resetSortOrderAndFilterCommit } = useResetSortOrderAndFilterTransaction();

  const deleteOrderButtonClicked = async () => {
    await deleteOrder({ id: params.orderId });
    // extracted transaction execution
    resetSortOrderAndFilterCommit();
  };

  return { deleteOrderButtonClicked };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <>
      <button onClick={controller.deleteOrderButtonClicked}>Delete</button>
      <div style={{ padding: "5px" }}>
        {presenter.itemIds.map((itemId) => (
          <OrderItem key={itemId} itemId={itemId} />
        ))}
      </div>
    </>
  );
};

Naming of an extracted transaction is suggested to be based on the logic it performs followed by the suffix Transaction.

At this stage the transaction unit implementation is considered complete.

Q&A

How to test the transactions?

Transaction units can be tested both in integration with other units they depend on and in isolation by mocking dependencies.

Where to place it?

Transactions are suggested to be placed in a dedicated transactions directory.

What is the transaction interface and do I need a specific one?

The minimal requirement for a transaction type is a function which does not return anything, because control flow goes reactively to the view unit through the store unit. As practice shows, it's best to have a globally defined transaction type where the function returns void.

export type Transaction<T = void> = {
  commit: (params: T) => void;
};

const useResetSortOrderAndFilterTransaction = (): Transaction => {
  const setFilterById = useItemsFilterStore((state) => state.setFilterById);
  const setSortOrder = useOrdersSortOrderStore((state) => state.setSortOrder);
  return {
    commit: () => {
      setFilterById(null);
      setSortOrder('asc');
    },
  };
};

const useController = (params: { orderId: string }): Controller => {
  const resource = useOrdersResourceSelector();
  const { mutateAsync: deleteOrder } = useMutation({ ...useDeleteOrderOptions(resource) });
  const { commit: resetSortOrderAndFilterCommit } = useResetSortOrderAndFilterTransaction();

  const deleteOrderButtonClicked = async () => {
    await deleteOrder({ id: params.orderId });
    // extracted transaction execution
    resetSortOrderAndFilterCommit();
  };

  return { deleteOrderButtonClicked };
};

Can I use a transaction inside another transaction?

Yes, as practice shows, transactions can be used inside other transactions. The main concern here is whether the store manager will be able to batch such transactions or provide API to batch em. If not, then it is suggested to implement a custom transaction that reflects the current need.

Can I use multiple transactions at once?

Yes, multiple transactions can be used at once. The main concern here the same as for nested transaction usage.

Conclusion

Transaction is simple but yet powerful unit for managing state transitions. It ensures consistency, encapsulates complex logic, and enables reuse across different usecases. Starting with inline transaction and evolving to extracted one allows for flexibility and scalability as the application grows.

Use Case Interactor Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Tue, 08 Apr 2025 13:15:12 +0000

This article shares the concept and implementation of the use case interactor unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Use Case Interactor Implementation
- Inline Use Case Interactor Implementation
- Extracted Use Case Interactor Implementation
Q&A
- How to test the Use Case Interactor?
- Where to place it?
- What is the Use Case Interactor interface and do I need a specific one?
- Can I use a Use Case Interactor inside another Use Case Interactor? Can I use multiple Use Case Interactors at once?
- The CLI interface is not reactive. How can you use a use case interactor in this context?
Conclusion

The use case interactor is a unit that orchestrates the application by coordinating entities, gateways, and transactions to fulfill specific user goals. It implements application business rules.

The unit does not return any data because, according to unified data flow, the data flows from the unit into the view unit through entities, gateways, and selectors.

Use Case Interactor Implementation

The implements an interface provided by a consumer. The interface could be just a function which the use case interactor should provide or a more complex one used globally across the application.

The unit has two possible implementation types: inline and extracted. In practice, the unit evolves in the following way:

 -----------------        --------------------
| inline Use Case | ---> | extracted Use Case |
 -----------------        --------------------

Any use case interactor implementation starts from a simple inline function in a consumer (controller).

All development context is focused on the application orchestration logic only.

Inline Use Case Interactor Implementation

Let's look at a basic example, where we have already implemented the view and
controller.

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked(id: string): Promise<void>;
}

const useController = (params: { orderId: string }): Controller => {
  // mocked controller handler
  const deleteOrderButtonClicked = async () => {};

  return { deleteOrderButtonClicked };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <>
      <button onClick={controller.deleteOrderButtonClicked}>Delete</button>
      <div style={{ padding: "5px" }}>
        {presenter.itemIds.map((itemId) => (
          <OrderItem key={itemId} itemId={itemId} />
        ))}
      </div>
    </>
  );
};

The use case interactor should delete an order in a remote source and reset the items filter. Observing the codebase, we found that filter values are stored in the store and remote orders can be deleted with a mutation call. Then implementation of inline use case interactor could look next:

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked(id: string): Promise<void>;
}

const useController = (params: { orderId: string }): Controller => {
  const setItemsFilterById = useOrdersPresentationStore((state) => state.setItemsFilterById);

  const resource = useOrdersResourceSelector();
  const { mutateAsync: deleteOrder } = useMutation({ ...useDeleteOrderOptions(resource) });

  // controller handler
  const deleteOrderButtonClicked = async () => {
    // inline use case interactor
    await deleteOrder({ id: params.orderId }); // order deletion through the gateway
    setItemsFilterById(null); // pessimistic update of the entity store
  };

  return { deleteOrderButtonClicked };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <>
      <button onClick={controller.deleteOrderButtonClicked}>Delete</button>
      <div style={{ padding: "5px" }}>
        {presenter.itemIds.map((itemId) => (
          <OrderItem key={itemId} itemId={itemId} />
        ))}
      </div>
    </>
  );
};

Extracted Use Case Interactor Implementation

The final step is to observe the codebase for the need of use case interactor extraction and reuse. The extraction happens if any other consumer unit already has the same logic implemented or the use case interactor becomes more complex. In this case, the inline use case interactor evolves to an extracted use case interactor.

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked(id: string): Promise<void>;
}

// extracted use case interactor
export const useDeleteOrderUseCase = (): { execute: (params: { orderId: string }) => Promise<void> } => {
  const setItemsFilterById = useOrdersPresentationStore((state) => state.setItemsFilterById);
  const resource = useOrdersResourceSelector();
  const { mutateAsync: deleteOrder } = useMutation({ ...useDeleteOrderOptions(resource) });

  const execute = async (params: { orderId: string }) => {
    await deleteOrder({ id: params.orderId }); // order deletion through the gateway
    setItemsFilterById(null); // // pessimistic update of the entity store
  };

  return { execute };
};

const useController = (params: { orderId: string }): Controller => {
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  // controller handler
  const deleteOrderButtonClicked = async () => {
    // use case interactor execution
    await executeDeleteOrderUseCase({ orderId: params.orderId });
  };

  return { deleteOrderButtonClicked };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <>
      <button onClick={controller.deleteOrderButtonClicked}>Delete</button>
      <div style={{ padding: "5px" }}>
        {presenter.itemIds.map((itemId) => (
          <OrderItem key={itemId} itemId={itemId} />
        ))}
      </div>
    </>
  );
};

Naming of an extracted unit is suggested to be based on the logic it performs followed by the suffix UseCase.

At this stage the use case interactor unit implementation is considered complete.

Q&A

How to test the Use Case Interactor?

Use case interactor units can be tested both in integration with other units they depend on and in isolation by mocking dependencies. An example can be found here: useDeleteOrderUseCase.spec.tsx

Where to place it?

Use case interactors are suggested to be placed in a dedicated useCases directory.

What is the Use Case Interactor interface and do I need a specific one?

The minimal requirement for a use case interactor type is a function which does not return anything, because control flow goes reactively to the view unit through the store unit. As practice shows, it's best to have a globally defined use case interactor type where the function returns Promise<void>.

export type UseCase<T = void> = {
  execute: (params: T) => Promise<void>;
};

export const useDeleteOrderUseCase = (): UseCase<{ orderId: string }> => {
  const setItemsFilterById = useOrdersPresentationStore((state) => state.setItemsFilterById);
  const resource = useOrdersResourceSelector();
  const { mutateAsync: deleteOrder } = useMutation({ ...useDeleteOrderOptions(resource) });

  const execute = async (params: { orderId: string }) => {
    await deleteOrder({ id: params.orderId });
    setItemsFilterById(null);
  };

  return { execute };
};

const useController = (params: { orderId: string }): Controller => {
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  const deleteOrderButtonClicked = async () => {
    await executeDeleteOrderUseCase({ orderId: params.orderId });
  };

  return { deleteOrderButtonClicked };
};

Can I use a Use Case Interactor inside another Use Case Interactor? Can I use multiple Use Case Interactors at once?

Yes, you can technically use multiple use case interactors at once, but doing so can create a complex dependency graph and make the codebase difficult to maintain. Keep in mind that executing these units may trigger asynchronous state changes in the entities store, which can cause intermediate re-renders of the view unit. Additionally, if one of several interactors fails with an error, it may lead to an inconsistent application state. In practice, it is recommended to build a custom use case interactor from shared selectors, effects, and transaction units that reflect the current need.

// Example of using multiple subsequent use case interactors
const useController = (params: { orderId: string }): Controller => {
  // useDeleteOrderUseCase is a Use Case Interactor that pessimistically deletes
  // order triggering update of the store unit and the view unit rerender
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();
  // useUpdateOrdersUseCase is a Use Case Interactor that updates orders of the
  // store unit and the view unit rerender
  const { execute: executeUpdateOrdersUseCase } = useUpdateOrdersUseCase();

  const deleteOrderButtonClicked = async () => {
    await executeDeleteOrderUseCase({ orderId: params.orderId });
    // rerender of view unit
    // should this be executed, if the deleteOrderUseCase fails?
    await executeUpdateOrdersUseCase();
    // rerender of view unit
  };

  return { deleteOrderButtonClicked };
};

The CLI interface is not reactive. How can you use a use case interactor in this context?

To use a use case interactor in a non-reactive context, such as a CLI, you can extend its type to return a value that indicates whether the execution was successful or not.

type UseCaseSuccess = void;
type UseCaseFailure = Error;

export type UseCase<T = void> = {
  execute: (params: T) => Promise<UseCaseSuccess | UseCaseFailure>;
};

Then use case interactor which implements the interface could be used like this.

declare global {
  interface Window {
    deleteOrder?: (id: unknown) => Promise<number[]>;
  }
}

export const DeleteOrderCliCommand: FC = memo(() => {
  const presenter = usePresenter();
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  useEffect(() => {
    window.deleteOrder = async (id: unknown) => {
      if (!isOrderEntityId(id)) {
        return "Invalid order id";
      }
      const result = await executeDeleteOrderUseCase({ orderId: id });
      // depending on result presenter returns remaining order ids or error
      const output = await presenter({ orderId: id, result });
      console.log(output)
    };
    return () => {
      delete window.deleteOrder;
    };
  }, [executeDeleteOrderUseCase, presenter]);

  return null;
});

Conclusion

The use case interactor unit is one of the most important and powerful tools that orchestrates the application. The unit encapsulates the application business logic. Starting with inline use case interactor and extract them only when necessary, allowing your architecture to evolve naturally with your application's complexity.

Selector Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Tue, 01 Apr 2025 07:52:42 +0000

This article shares the concept and implementation of the selector unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Selector Implementation
- Inline Selector Implementation
- Extracted Selector Implementation
Q&A
- How to test the selector?
- Where to place it?
- What is the selector interface and do I need a specific one?
Conclusion

Selector is a unit that derives values or data structures from the state without modifying it. It implements read-only queries against the state and contains application-specific logic. Selectors do not do any side effects.

The selector unit primarily depends on the entity store for data access. Some selectors may also depend on gateways when additional data is needed, such as fetch states or cached entity data. These gateway dependencies are possible when gateways are implemented using libraries like TanStack React Query or RTK Query.

Selector Implementation

The selector implements interface provided by a consumer. The interface could be just a data type which selector should return or a more complex one, used globally across the application.

The unit has two possible implementation types: inline and extracted. In practice, the unit evolves in the following way:

--------------------      ----------------------
| inline  selector | ---> | extracted selector |
--------------------      ----------------------

Any selector implementation starts from a simple inline function in a consumer.

All development context is focused on the selection logic only.

Inline Selector Implementation

Let's look at a basic example, where we have already view and presenter implemented.

interface OrderProps {
  orderId: string;
}

interface Presenter {
  itemIds: string[];
}

const usePresenter = (params: { orderId: string }): Presenter => {
  return {
    itemIds: ['itemId1', 'itemId2'],
  };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);

  return (
    <div style={{ padding: "5px" }}>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

The selector we need should retrieve items of a specific order, filter them based on a filter value, and return an array. The resulting array should be an array of strings, because the presenter indicates that the property itemIds requires a type of string[]. The data type of the output is already defined, so our main concern is to determine where and how to select the data.

Observing the codebase we found that filter values are stored in the store and for the order entity there is already an implemented selector. In this case the required selector implementation can be done following way.

interface OrderProps {
  orderId: string;
}

interface Presenter {
  itemIds: string[];
}

const usePresenter = (params: { orderId: string }): Presenter => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  return {
    // inline selector attached to the itemIds property
    itemIds:
      order?.itemEntities
        .filter((itemId) => visibleItemsIds.includes(itemId))
        .map((itemEntity) => itemEntity.id) ?? [],
  };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);

  return (
    <div style={{ padding: "5px" }}>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Extracted Selector Implementation

Final step is to observe codebase for the need of selector extraction and reuse. The extraction happens if any other consumer unit already has same logic implemented or the selector became more complex. In this case inline selector evolves to extracted selector.

// extracted selector
export const useVisibleItemIdsSelector = (params: { orderId: string }): string[] => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  return (
    order?.itemEntities
      .filter((itemId) => visibleItemsIds.includes(itemId))
      .map((itemEntity) => itemEntity.id) ?? []
  );
};

interface OrderProps {
  orderId: string;
}

interface Presenter {
  itemIds: string[];
}

const usePresenter = (params: { orderId: string }): Presenter => {
  const visibleItemIds = useVisibleItemIdsSelector(props.orderId);
  return {
    itemIds: visibleItemIds,
  };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);

  return (
    <div style={{ padding: "5px" }}>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Another approach to extracting selector is to split inline selector into extracted selector and presenter mapper.

// extracted selector
export const useVisibleItemsSelector = (params: { orderId: string }): ItemEntity[] => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  return order?.itemEntities.filter((itemId) => visibleItemsIds.includes(itemId));
};

interface OrderProps {
  orderId: string;
}

interface Presenter {
  itemIds: string[];
}

const usePresenter = (params: { orderId: string }): Presenter => {
  const visibleItemEntities = useVisibleItemsSelector(props.orderId);
  return {
    itemIds: visibleItemEntities.map(toItemEntityId);
  };
};

// presenter mapper
const toItemEntityId = (item: ItemEntity): string => item.id

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);

  return (
    <div style={{ padding: "5px" }}>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

The approach of selector extraction should reflect current selector usage needs. Naming of extracted selector is suggested to be based on the data it extracts followed by the suffix Selector.

At this stage the selector unit implementation is considered complete.

Q&A

How to test the selector?

Selector units can be tested in integration with other units they depend on, in isolation by mocking dependencies or by extracting core logic.

Example of integration test can be found in useTotalItemsQuantitySelector.spec.tsx.

Let's look at the example with core logic extraction.

The selector has inline select (core) logic.

// extracted selector
export const useVisibleItemIdsSelector = (params: { orderId: string }): string[] => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  return (
    // select (core) logic
    order?.itemEntities
      .filter((itemId) => visibleItemsIds.includes(itemId))
      .map((itemEntity) => itemEntity.id) ?? []
  );
};

Once the select logic is extracted, the selector will look like this.

// extracted selector
export const useVisibleItemIdsSelector = (params: { orderId: string }): string[] => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  return select(order, visibleItemsIds);
};

// extracted select (core) logic
export const select = (order: OrderEntity | undefined, visibleItemsIds: string[]): string[] => {
  return (
    order?.itemEntities
      .filter((itemId) => visibleItemsIds.includes(itemId))
      .map((itemEntity) => itemEntity.id) ?? []
  );
};

The select is a pure function, which can be pretty easily tested with just mock data passed as arguments.

Where to place it?

Selectors are suggested to be placed in a dedicated useCases directory.

What is the selector interface and do I need a specific one?

The minimal requirement is that a consumer specifies the type for the data it needs, and the selector returns that specific data type. In more complex cases, an application might define a global selector interface that both consumers and selectors should use.

The example below demonstrates a simple selector. The return type of the selector is determined by the type annotation of the itemsIds property in the presenter interface.

interface Presenter {
  // Presenter interface defines type of `itemsIds`
  itemIds: string[];
}

// The selector is implemented to return the type requested by the presenter
const useVisibleItemIdsSelector = (params: { orderId: string }): string[] => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  return (
    order?.itemEntities
      .filter((itemId) => visibleItemsIds.includes(itemId))
      .map((itemEntity) => itemEntity.id) ?? []
  );
};

// Now the selector is used to the presenter implementation
const usePresenter = (params: { orderId: string }): Presenter => {
  const itemIds = useVisibleItemIdsSelector(props.orderId);
  return {
    itemIds
  };
};

Next example shows the same selector implementation, but with the use of global Selector interface definition withing an application. This approach is not necessary, but it can be useful in some cases, e.g., dependency injection, providing options to select operation in specific contexts.

// Global selector type
type Selector<R, T extends unknown[] = []> = {
  select: (...params: T) => R;
};

interface Presenter {
  // Presenter interface defines type of `itemsIds`
  itemIds: string[];
}

// Selector implementation, which requires injection of `visibleItemIdsSelector`
// and `orderByIdSelector`
const useVisibleItemIdsByOrderIdSelector = (params: {
  visibleItemIdsSelector: Selector<string[]>;
  orderbyIdSelector: Selector<OrderEntity>;
}): Selector<string[]> => {
  return {
    select: () => {
      const visibleItemsIds = params.visibleItemIdsSelector.select();
      const order = params.orderByIdSelector.select();
      return (
        order?.itemEntities
          .filter((itemId) => visibleItemsIds.includes(itemId))
          .map((itemEntity) => itemEntity.id) ?? []
      );
    },
  };
};

// Presenter implementation, which requires injection of `visibleItemIdsSelector`
const usePresenter = (params: {
  visibleItemIdsByOrderIdSelector: Selector<string[]>;
}): Presenter => {
  return {
    itemIds: params.visibleItemIdsByOrderIdSelector.select(),
  };
};

Conclusion

Selector is essential unit in Clean Architecture for frontend applications. It provides a consistent and maintainable way to derive data from the application state. By using selectors, developers can keep the state clean and effectively separate application logic from enterprise logic.

Controller and Presenter Units in Clean Architecture for Frontend Applications

Dzmitry Harunou — Tue, 25 Mar 2025 08:54:00 +0000

This article shares the concept and implementation of the presenter and controller units in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

Controller and Presenter Implementation
- Controller and Presenter Implementation Types
- Null Presenter and Null Controller Implementation
- Inline Controller and Inline Presenter Implementation
- Extracted Controller and Extracted Presenter Implementation
Q&A
- Why does architecture use separate controller and presenter units instead of a single ViewModel object or similar?
- How to test the presenter and controller?
- Where should I place extracted controller and presenter?
- Can controller and presenter work with props instead of the application core?
- Can props already be the presenter and controller interfaces?
Conclusion

Presenter and controller are adapter units that facilitate the connection between the view and the application core or parent component. The presenter is responsible for mapping incoming data to the format required by the view. The controller maps data from the view to an outgoing format understood by, for example, the application core or a parent component.

Controllers and presenters are not shared between views and components.

Controller and Presenter Implementation

Controller and presenter implement interfaces defined by the view and represent the view's contract with the application core. The sole responsibility of these units is transformation logic.

The development context is limited to the data transformation logic and the type of the unit implementation.

Controller and Presenter Implementation Types

Typically, the unit has three possible implementation types: null, inline, and extracted. In practice, the unit evolves in the following way (example based on the presenter unit):

------------------      ---------------------      -----------------------
| null presenter | ---> | inline  presenter | ---> | extracted presenter |
------------------      ---------------------      -----------------------

Null Presenter and Null Controller Implementation

When the view is simple and doesn't have explicit presenter and/or controller interfaces defined, the controller and presenter can be implemented directly with constants inside a component. This implementation is called "null presenter" or "null controller".

In the example below, the component contains presenter and controller implementations that use mock data. The itemIds constant serves as null presenter property, while the deleteOrderButtonClicked function serves as null controller method.

interface OrderProps {
  orderId: string;
}

export const Order: FC<OrderProps> = (props) => {
  // null presenter implementation
  const itemIds = ["1", "2"];

  // null controller implementation
  const deleteOrderButtonClicked = () => {};

  // view implementation
  return (
    <div style={{ padding: "5px" }}>
      <button onClick={deleteOrderButtonClicked}>
        Delete Order
      </button>
      {itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Next example demonstrates a complete component implementation with null presenter and null controller when the component is connected to the application core.

interface OrderProps {
  orderId: string;
}

export const Order: FC<OrderProps> = (props) => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  const itemIds =
    order?.itemEntities
      .map((itemEntity) => itemEntity.id)
      .filter((itemId) => visibleItemsIds.includes(itemId)) ?? [];

  const deleteOrderButtonClicked = async () => {
    await executeDeleteOrderUseCase(props.orderId);
  };

  return (
    <div style={{ padding: "5px" }}>
      <button onClick={deleteOrderButtonClicked}>
        Delete Order
      </button>
      {itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Inline Controller and Inline Presenter Implementation

In some cases, it is possible to implement the presenter and/or the controller inline in the component. This approach is suitable when the transformation logic is simple and the view has presenter and/or controller interfaces declared. Additionally, it can serve as an intermediate step before fully extracting the presenter and/or controller. The example below shows inline controller and presenter implementations that use mock data.

interface OrderProps {
  orderId: string;
}

interface Presenter {
  itemIds: string[];
}

interface Controller {
  deleteOrderButtonClicked: () => void;
}

export const Order: FC<OrderProps> = (props) => {
  // inline presenter implementation
  const presenter: Presenter = {
    itemIds: ["1", "2"],
  };

  // inline controller implementation
  const controller: Controller = {
    deleteOrderButtonClicked: () => {},
  };

  // view implementation
  return (
    <div style={{ padding: "5px" }}>
      <button onClick={controller.deleteOrderButtonClicked}>
        Delete Order
      </button>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Next example demonstrates a complete component implementation with inline presenter and controller when the component is connected to the application core.

interface OrderProps {
  orderId: string;
}

interface Presenter {
  itemIds: string[];
}

interface Controller {
  deleteOrderButtonClicked: () => void;
}

export const Order: FC<OrderProps> = (props) => {
  const visibleItemsIds = useOrdersPresentationStore((state) => state.itemsFilterById);
  const order = useOrderByIdSelector(props.orderId);
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  const presenter: Presenter = {
    itemIds:
      order?.itemEntities
        .map((itemEntity) => itemEntity.id)
        .filter((itemId) => visibleItemsIds.includes(itemId)) ?? [],
  };

  const controller: Controller = {
    deleteOrderButtonClicked: async () => {
      await executeDeleteOrderUseCase(props.orderId);
    },
  };

  return (
    <div style={{ padding: "5px" }}>
      <button onClick={controller.deleteOrderButtonClicked}>
        Delete Order
      </button>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Extracted Controller and Extracted Presenter Implementation

When the adapter logic is complex, it is better to extract the units from the component. For this, the view should have clearly defined controller and presenter interfaces. Extracted presenter and controller are ordinary objects created with class constructors or functions. The example below demonstrates presenter and controller created with React hooks. Both presenter and controller are using mock data.

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked: () => void;
}

interface Presenter {
  itemIds: string[];
}

// extracted presenter implementation
const usePresenter = (): Presenter => {
  return {
    itemIds: ["1", "2"],
  };
};

// extracted controller implementation
const useController = (): Controller => {
  return {
    deleteOrderButtonClicked: () => {}
  };
};

export const Order: FC<OrderProps> = (props) => {
  // extracted presenter usage
  const presenter = usePresenter();
  // extracted controller usage
  const controller = useController();

  // view implementation
  return (
    <div style={{ padding: "5px" }}>
      <button onClick={controller.deleteOrderButtonClicked}>
        Delete Order
      </button>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Next example demonstrates a complete component implementation with extracted presenter and controller when the component is connected to the application core. When needed, the unit could receive a constructor argument that defines its operational mode. In the example, the presenter and the controller receive an orderId, which determines which OrderEntity to operate with.

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked: () => void;
}

interface Presenter {
  itemIds: string[];
}

const usePresenter = (params: { orderId: string }): Presenter => {
  const order = useOrderByIdSelector(params.orderId);

  return {
    itemIds: order.itemEntities.map((itemEntity) => itemEntity.id),
  };
};

const useController = (params: { orderId: string }): Controller => {
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  return {
    deleteOrderButtonClicked: async () => {
      await executeDeleteOrderUseCase(params.orderId);
    }
  };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <div style={{ padding: "5px" }}>
      <button onClick={controller.deleteOrderButtonClicked}>
        Delete Order
      </button>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

If transformation logic is extensive, it could be extracted to a separate mapper function, for example:

interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked: () => void;
}

interface Presenter {
  itemIds: string[];
}

const usePresenter = (params: { orderId: string }): Presenter => {
  const order = useOrderByIdSelector(params.orderId);

  return {
    itemIds: order.itemEntities.map(toItemId),
  };
};

// mapper function containing transformation logic
const toItemId = (itemEntity: OrderEntity) => itemEntity.id;

const useController = (params: { orderId: string }): Controller => {
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  return {
    deleteOrderButtonClicked: async () => {
      await executeDeleteOrderUseCase(params.orderId);
    }
  };
};

export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <div style={{ padding: "5px" }}>
      <button onClick={controller.deleteOrderButtonClicked}>Delete Order</button>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

At this point, the controller and presenter are considered implemented. The next possible step is connecting them to the application core by implementing presenter and controller properties one by one with already existing use cases, entities, and selectors or by creating new ones.

Q&A

Why does architecture use separate controller and presenter units instead of a single ViewModel object or similar?

In frontend clean architecture, controllers and presenters are preferred over a single ViewModel object or similar for several reasons:

Separation of Concerns and Explicit Boundaries, CQS Principle: Controllers handle user interactions and event logic, while presenters focus on preparing data for display. This clear division, rooted in the Command Query Separation (CQS) principle, ensures that commands (controller: actions, mutations) and queries (presenter: data, selectors) are handled by distinct units. As a result, responsibilities do not mix, boundaries between the view and application core are well-defined, and controllers do not rely on presenter properties. This leads to more maintainable, testable, and predictable code.
Flexibility: Controllers and presenters can evolve separately. For example, complex data mapping can be moved to the presenter, while new user actions can be added to the controller, without affecting each other or the view.
Avoiding Overloaded Objects: A ViewModel often becomes a catch-all for both data and behavior, which can lead to bloated, hard-to-maintain objects. Controllers and presenters keep logic focused and lightweight.

This approach aligns with the principles of clean architecture and CQS, ensuring that each unit has a single responsibility and that the system remains adaptable and robust as requirements change.

export const Order: FC<OrderProps> = (props) => {
  // presenter unit: provides queries to the core
  // <--- data in
  const presenter = usePresenter();

  // controller unit: sends commands to the core
  // data out --->
  const controller = useController();

  // view unit
  return (
    <div style={{ padding: "5px" }}>
      <button onClick={controller.deleteOrderButtonClicked}>
        Delete Order
      </button>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

How to test the presenter and controller?

The presenter and controller units can be tested through unit integration tests with the application core. Mapper functions, being pure functions with no dependencies, can be easily tested in isolation.

Where should I place extracted controller and presenter?

The extracted controller and presenter are better placed in separate files along with consuming component. The example below demonstrates a possible file structure:

// file: ./Order.types.ts
interface OrderProps {
  orderId: string;
}

interface Controller {
  deleteOrderButtonClicked: () => void;
}

interface Presenter {
  itemIds: string[];
}

// file: ./hooks/usePresenter.ts
const usePresenter = (params: { orderId: string }): Presenter => {
  const order = useOrderByIdSelector(params.orderId);

  return {
    itemIds: order.itemEntities.map(toItemId),
  };
};

// file: ./hooks/mappers.ts
const toItemId = (itemEntity: OrderEntity) => itemEntity.id;

// file: ./hooks/useController.ts
const useController = (params: { orderId: string }): Controller => {
  const { execute: executeDeleteOrderUseCase } = useDeleteOrderUseCase();

  return {
    deleteOrderButtonClicked: async () => {
      await executeDeleteOrderUseCase(params.orderId);
    }
  };
};

// file: ./Order.tsx
export const Order: FC<OrderProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <div style={{ padding: "5px" }}>
      <button onClick={controller.deleteOrderButtonClicked}>
        Delete Order
      </button>
      {presenter.itemIds.map((itemId) => (
        <OrderItem key={itemId} itemId={itemId} />
      ))}
    </div>
  );
};

Can controller and presenter work with props instead of the application core?

Yes. Controller and presenter can adapt data coming from props instead of the application core. The presenter maps raw prop values into display-ready format, while the controller maps view events back to prop callbacks. The view remains unaware of the prop shapes or callback signatures.

// file: ./UserCard.types.ts
interface UserCardProps {
  firstName: string;
  lastName: string;
  birthYear: number;
  onSelect: () => void;
}

interface Presenter {
  fullName: string;
  age: number;
}

interface Controller {
  selectButtonClicked: () => void;
}

// file: ./hooks/usePresenter.ts
const usePresenter = (props: UserCardProps): Presenter => ({
  fullName: `${props.firstName} ${props.lastName}`,
  age: new Date().getFullYear() - props.birthYear,
});

// file: ./hooks/useController.ts
const useController = (props: UserCardProps): Controller => ({
  selectButtonClicked: () => props.onSelect(),
});

// file: ./UserCard.tsx
export const UserCard: FC<UserCardProps> = (props) => {
  const presenter = usePresenter(props);
  const controller = useController(props);

  return (
    <div>
      <p>{presenter.fullName}</p>
      <p>{presenter.age} years old</p>
      <button onClick={controller.selectButtonClicked}>Select</button>
    </div>
  );
};

The presenter derives fullName and age from the raw props. The controller closes over onSelect and exposes it under a view-specific name. If the prop interface changes, only the presenter and controller need to be updated - the view stays intact.

Can props already be the presenter and controller interfaces?

Yes. When the presenter and controller interfaces are merged with props, the component signals to the parent that it expects already adapted data. The parent takes on the responsibility of preparing and passing down the correct format.

type UserCardProps = Presenter & Controller

type Presenter = {
  fullName: string;
  age: number;
}

type Controller = {
  selectButtonClicked: () => void;
}

export const UserCard: FC<UserCardProps> = (props) => {
  return (
    <div>
      <p>{props.fullName}</p>
      <p>{props.age} years old</p>
      <button onClick={props.selectButtonClicked}>Select</button>
    </div>
  );
};

In this case the presenter and controller implementations are not needed inside the component - the adaptation responsibility has moved up to the parent.

Conclusion

Controllers and presenters serve as essential adapters, creating a clear boundary between the view and application core. By starting with null implementation and progressing to inline and extracted patterns as complexity grows, developers can maintain separation of concerns while adapting to changing requirements. This approach results in more maintainable components with well-defined responsibilities and interfaces.

View Unit in Clean Architecture for Frontend Applications

Dzmitry Harunou — Tue, 18 Mar 2025 07:58:00 +0000

This article shares the concept and implementation of the view unit in frontend applications within the Clean Architecture.

Repository with example:
https://github.com/harunou/react-tanstack-react-query-clean-architecture

View Visualization
View Implementation
Q&A
- How to test the view?
- Do I need to create presenter and controller interfaces for each component?
- Understanding null interface
- Where should I place presenter and controller interfaces?
- How can interfaces help improve component design?
Conclusion

View unit is typically a layout. For example, in a React component, the layout is represented with JSX. The role of the view is to present the application's data to the user and handle user input. The view is tightly coupled with the presenter and controller interfaces, which summarize the data and event handlers required for the view.

View Visualization

The image demonstrates a component diagram and its elements and dependencies.

As mentioned in the overview, the view depends on presenter and controller through provided interfaces. The controller and presenter implement these interfaces and depend on the application core. Additionally, the controller and presenter could depend on props or/and the component's local state whenever needed.

The control flow and data flow are straightforward:

Data adapted for presentation flows from the presenter into the view, while the controller handles user events captured by the view.

View Implementation

View implementation is pretty formal and starts from a visual design. The design is translated into a layout. Development context is limited to everything related to visual representation: layout structure, styles, animations, design system, component library, accessibility, etc. There is no need to guess about a store or external resources - this will be addressed later. The end result consists of three elements: the component layout, the controller interface and the presenter interface where it is necessary.

Let's look at an example.

At the very beginning, the layout is empty; the component returns null, not JSX. The presenter and controller interfaces are empty as well.

interface Presenter {
}

interface Controller {
}

export const Order: FC = () => {
  const presenter: Presenter = {};
  const controller: Controller = {};

  return null;
};

Step by step, the layout is built, and the interfaces are gradually filled with properties. The naming convention for properties in the presenter and controller interfaces follows a simple pattern: presenter property names reflect the data that needs to be presented, while controller property names are event-based and clearly reflect the actions that need to be handled by the component.

interface Presenter {
  hasOrder: boolean;
  orderDate: string;
  userName: string;
}

interface Controller {
  deleteOrderButtonClicked: () => void;
}

export const Order: FC = () => {
  // presenter implementation with mock data
  const presenter: Presenter = {
    hasOrder: true,
    orderDate: "09-03-2025",
    userName: "John Doe",
  };

  // controller implementation with mock data
  const controller: Controller = {
    deleteOrderButtonClicked: () => {},
  };

  if (!presenter.hasOrder) {
    return null;
  }

  return (
    <div style={{ border: "1px solid red" }}>
      <button onClick={controller.deleteOrderButtonClicked}>
        Delete Order
      </button>
      <div>Date: {presenter.orderDate}</div>
      <div>User name: {presenter.userName}</div>
    </div>
  );
};

Any further view improvements or updates should also remain within the boundaries of layout and interfaces.

At the point, when the view meets all visual requirements and has controller and presenter interfaces defined, the view implementation can be considered complete. Next possible step is to create controller and presenter.

Q&A

How to test the view?

A view can be tested manually because it can be rendered in a browser with mock data. Additionally, the view can be tested by creating unit tests with mocked controller and presenter interfaces. An example can be found here: Orders.spec.tsx

Do I need to create presenter and controller interfaces for each component?

No, it depends on the complexity of the view. If the view is simple, where values and handlers can be easily observed, then it's not necessary. The interfaces summarize the data and actions that the view needs to present and handle. If you can build such a summary in your head without an interface declaration, the declaration can be omitted.

Understanding null interface

If a view is simple, it may not need to declare explicit interfaces and can instead rely on “null presenter” or “null controller” interfaces.

The example below demonstrates a view with a null presenter interface. The constants hasOrder, orderDate, and userName act as properties of the null presenter implementation and are assigned mock data.

export const Order: FC = () => {
  // Constants representing the null presenter implementation
  const hasOrder = true;
  const orderDate = "09-03-2025";
  const userName = "John Doe";

  if (!hasOrder) {
    return null;
  }

  return (
    <div style={{ padding: "5px" }}>
      <div>Date: {orderDate}</div>
      <div>User name: {userName}</div>
    </div>
  );
};

Next example demonstrates same view with presenter interface. The constant presenter represents presenter assigned with mock data.

interface Presenter {
  hasOrder: boolean;
  orderDate: string;
  userName: string;
}

export const Order: FC = () => {
  const presenter: Presenter = {
    hasOrder: true,
    orderDate: "09-03-2025",
    userName: "John Doe",
  };

  if (!presenter.hasOrder) {
    return null;
  }

  return (
    <div style={{ padding: "5px" }}>
      <div>Date: {presenter.orderDate}</div>
      <div>User name: {presenter.userName}</div>
    </div>
  );
};

Where should I place presenter and controller interfaces?

Once declared, the interfaces can be placed either in the same file as the component if they are implemented within that file:

// file:./Order.tsx
interface Presenter {
  hasOrder: boolean;
  orderDate: string;
  userName: string;
}

export const Order: FC = () => {
  const presenter: Presenter = {
    hasOrder: true,
    orderDate: "09-03-2025",
    userName: "John Doe",
  };

  if (!presenter.hasOrder) {
    return null;
  }

  return (
    <div style={{ border: "1px solid red" }}>
      <div>Date: {presenter.orderDate}</div>
      <div>User name: {presenter.userName}</div>
    </div>
  );
};

Alternatively, they can be placed in a separate file if the interfaces are implemented in a different file as well:

// file:./Order.types.ts
export interface Presenter {
  hasOrder: boolean;
  orderDate: string;
  userName: string;
}
t
// file:./presenter.ts
import type { Presenter } from "./Order.types.ts"

export const presenter: Presenter = {
  hasOrder: true,
  orderDate: "09-03-2025",
  userName: "John Doe",
}

// file:./Order.tsx
import { presenter } from "./presenter";

export const Order: FC = () => {
  if (!presenter.hasOrder) {
    return null;
  }

  return (
    <div style={{ border: "1px solid red" }}>
      <div>Date: {presenter.orderDate}</div>
      <div>User name: {presenter.userName}</div>
    </div>
  );
};

How can interfaces help improve component design?

Following the Interface Segregation Principle (ISP), large interfaces may indicate that a view is too complex and should be split into smaller, more specific parts. Interface declarations can help identify how a component can be decomposed.

Conclusion

View unit serves as the boundary between users and the system. When working with the view, the development context is limited to component layout and interfaces, reflecting the view's actual needs. The decision of whether to declare explicit presenter/controller interfaces should be guided by the component's complexity. The chosen consumption approach (props or presenter/controller implementations) can affect the number of props, properties in interfaces, and the view structure, but switching between approaches is not a big deal.

DEV Community: Dzmitry Harunou

Frontend Clean Architecture: Practical Insights and Pitfalls

Table of Contents

1. Implementation Is a UML Diagram

2. Hexagonal Architecture Terminology Can Obscure Clean Architecture

3. Codebase Evolution: The Overlooked Factor

4. Templates Undermine Agility

Conclusion

Development Workflow in Clean Architecture for Frontend Applications

Table of Contents

Step 1: Add view, controller, and presenter units

Step 2: Add entities store unit

Step 3: Add gateway unit factory

Step 4: Connect the presenter unit to the entities store unit

Step 5: Connect the controller unit to the entities store unit and the gateway unit

Step 6: Add the in-memory gateway unit

Step 7: Implement the external resource unit

Step 8: Add the remote gateway unit

Conclusion

Testing in Clean Architecture for Frontend Applications

Table of Contents

Unit Tests

Integration Tests

End-to-End (E2E) Tests

Conclusion

External Resource Unit in Clean Architecture for Frontend Applications

Table of Contents

External Resource Implementation

Q&A

How should the external resource unit be tested?

Where should the external resource unit be placed?

Can the external resource unit use entity types instead of declaring its own?

Conclusion

Gateway Unit in Clean Architecture for Frontend Applications

Table of Contents

Gateway Implementation

Q&A

How should the gateway unit be tested?

Where should gateways be placed?

Is a factory function required for the gateway unit?

Should the gateway unit always be implemented as a class?

The gateway unit depends on entities store unit. Why?

What can I do if an external resource is not yet defined?

Conclusion

Effect Unit in Clean Architecture for Frontend Applications

Table of Contents

Effect Implementation

Inline Effect Implementation

Extracted Effect Implementation

Q&A

How should an Effect unit be tested?

Where should Effects be placed?

Can Effects be nested?

Can multiple Effects be used simultaneously?

Conclusion

Entities Store Unit in Clean Architecture for Frontend Applications

Table of Contents

Store Implementation

Inline entities store implementation

Extracted entities store implementation

Q&A?

How to test the store?

Should domain and presentation stores be kept separate?

Conclusion

Transaction Unit in Clean Architecture for Frontend Applications

Table of Contents

Transaction Implementation

Inline Transaction Implementation

Extracted Transaction Implementation

Q&A

How to test the transactions?

Where to place it?

What is the transaction interface and do I need a specific one?

Can I use a transaction inside another transaction?

Can I use multiple transactions at once?

Conclusion

Use Case Interactor Unit in Clean Architecture for Frontend Applications

Table of Contents

Use Case Interactor Implementation

Inline Use Case Interactor Implementation