Business Domain (Entities)

Entities are the core business units of the project. This section describes the unified structure of any entity based on strict architectural rules.

Entities Layer Structure

Each business entity inside src/entities/* must follow a strict directory structure for logic and UI isolation.

File Structure

Standard Entity Modules

A complete entity consists of these required modules:

01/api

Responsible exclusively for network interaction with the backend application within a single entity. It takes arguments for the request and returns raw DTOs, which must then be passed to converters.

Learn RTK Query architecture

api/[entity-name].api.ts

import { mainApi } from "@/shared/api";

export const entityApi = mainApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<TResponse, TFilters>({
			query: (filters) => ({ url: "/entities" }),
			providesTags: [ENUM_API_TAGS.ENTITIES]
		})
	})
});

02/converters

Data mappers. They transform a raw server DTO into a convenient Domain Model. This isolates UI components from sudden changes in backend contracts.

Converters architecture

converters/[entity-name].converters.ts

export const mapEntityToFrontend = (data: IEntityBackend): IEntity => ({
	id: data.id,
	type: data.type as ENUM_ENTITY_TYPE,
	dateCreated: formatDate(data.date_created),
	client: data.client,
	status: data.status as ENUM_ENTITY_STATUS
});

export const mapEntityToBackend = (data: Partial<IEntityDetail>): 
	Partial<IEntityDetailBackend> => ({
		id: data.id,
		type: data.type,
		date_created: data.dateCreated,
		client: data.client,
		status: data.status
});

03/handlers

MSW (Mock Service Worker) handlers. Used to intercept network calls during development and in integration tests (Vitest / RTL).

How MSW works

handlers/[entity-name].handlers.ts

import { HttpResponse, http } from "msw";
import { ENV } from "@/shared/config";
import { ENTITIES_MOCK } from "../mock";

export const entityHandlers = [
	http.get(`${ENV.VITE_API_URL}/entities`, ({ request }) => {
		const url = new URL(request.url);
		return HttpResponse.json({
			data: [...ENTITIES_MOCK],
			total: ENTITIES_MOCK.length
		});
	}),
	http.get(`${ENV.VITE_API_URL}/entities/:id`, ({ params }) => {
		const entity = ENTITIES_MOCK.find((e) => e.id === params.id);
		if (!entity) return new HttpResponse(null, { status: 404 });
		return HttpResponse.json(entity);
	})
];

04/mock

Static fixtures and fake data (mock data) used to emulate server responses in conjunction with MSW handlers or for Storybook.

MSW and mock data section

mock/[entity-name].mock.ts

import type { IEntityDetail } from "../types";

export const ENTITIES_MOCK: IEntityDetail[] = [
	{
		id: "ENT-001",
		type: "individual",
		dateCreated: "2024-03-15T12:00:00Z",
		client: "John Doe",
		pax: 2,
		dates: { from: "2024-04-01", to: "2024-04-10" },
		status: "CONFIRMED",
		// ... full fields
	}
];

05/schema

Single Source of Truth for entity data types. Contains Zod objects with built-in internationalization (i18n) of errors.

Using Zod

schema/[entity-name].schema.ts

import { z } from "zod";
import { i18nKey } from "@/shared/config";

const msg = i18nKey<TEntityKeys>();

export const ENTITY_SCHEMA = z.object({
	client: z.string().min(1, { message: msg("errors.client.required") }),
	status: z.enum(["PENDING", "CONFIRMED"]),
	pax: z.number().min(1)
});

export type TEntitySchema = z.infer<typeof ENTITY_SCHEMA>;

06/slice

Redux state of the entity (if it stores global data). Selectors and actions often reside here as well. Note: state should depend solely on the Domain Model, not on DTOs.

slice/[entity-name].slice.ts

import { createSlice, PayloadAction } from "@reduxjs/toolkit";

interface IEntitySliceState {
	selectedId: string | null;
}

const initialState: IEntitySliceState = {
	selectedId: null
};

export const entitySlice = createSlice({
	name: "entity",
	initialState,
	reducers: {
		setSelectedEntity: (state, action: PayloadAction<string>) => {
			state.selectedId = action.payload;
		}
	}
});

07/ui

Dump or Smart components at the entity level. For example: UserCard, UserAvatar. Can be reused across different features and widgets.

ui/[entity-name]-card.tsx

interface IEntityCardProps {
	entity: IEntity;
	onSelect: (id: string) => void;
}

export const EntityCard = ({ entity, onSelect }: IEntityCardProps) => (
	<Card onClick={() => onSelect(entity.id)}>
		<CardHeader>{entity.client}</CardHeader>
		<CardContent>Pax: {entity.pax}</CardContent>
	</Card>
);

08/types

Global TS interfaces and types for a specific entity (e.g., Domain Model interface if Zod doesn't cover all logic). Type inference from Zod schemas is recommended, but when not possible, types are defined here.

Type inference in Zod

types/[entity-name].types.ts

export interface IEntityDates {
	from: string;
	to: string;
}

export interface IEntity {
	id: string;
	type: ENUM_ENTITY_TYPE;
	dateCreated: string;
	client: string;
	pax: number;
	dates: IEntityDates;
	status: ENUM_ENTITY_STATUS;
}