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

RTK Query endpoints for the entity. Converters run inside the API layer: transformResponse maps backend T*Backend to frontend models, and query maps params/body via map*ToBackend. Hooks already return domain models — UI must not re-map DTOs.

Learn RTK Query architecture

api/[entity-name].service.ts

import { baseApi } from "@/shared/api/backend";
import type { IPaginationRequest, IPaginationResponse } from "@/shared/types";
import {
	mapEntitiesQueryToBackend,
	mapEntitiesToFrontend
} from "../converters";
import type { TEntitiesBackend, IEntity } from "../types";

/** Converters run here — hooks return frontend models, not raw DTOs */
export const entityApi = baseApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<
			IPaginationResponse<IEntity>,
			IPaginationRequest
		>({
			query: (filters) => ({
				url: "/entities",
				params: mapEntitiesQueryToBackend(filters)
			}),
			transformResponse: (response: TEntitiesBackend) =>
				mapEntitiesToFrontend(response),
			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: TEntityBackend): 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 mapEntitiesToFrontend = (
	response: TEntitiesBackend
): IPaginationResponse<IEntity> => ({
	data: response.items.map(mapEntityToFrontend),
	total: response.total_count
});

export const mapEntityToBackend = (
	data: Partial<IEntityDetail>
): Partial<TEntityDetailBackend> => ({
	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 } from "msw";
import { createMockHandler } from "@/shared/api/msw/utils";
import { listEntitiesBackend } from "../mock";

/** Backend DTO responses — converters run in RTK transformResponse */
export const entityHandlers = [
	createMockHandler(
		{ url: "/entities", method: "GET", _types: { body: undefined } },
		() => HttpResponse.json(listEntitiesBackend())
	),
	createMockHandler(
		{ url: "/entities/:id", method: "GET", _types: { body: undefined } },
		({ params }) => {
			const { items } = listEntitiesBackend();
			const entity = items.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 { TEntityBackend } from "../types";

export const ENTITIES_MOCK: TEntityBackend[] = [
	{
		id: "ENT-001",
		type: "individual",
		date_created: "2024-03-15T12:00:00Z",
		client: "John Doe",
		pax: 2,
		status_code: "CONFIRMED"
	}
];

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]-create.schema.ts

import { z } from "zod";
import { i18nKey } from "@/shared/config";
// прямой путь к form.types — не barrel "../types"
import { ENUM_FORM_ENTITY_CREATE } from "../types/entity-create-form.types";

const msg = i18nKey<TEntityKeys>();
const F = ENUM_FORM_ENTITY_CREATE;

/** Runtime only — inferred form types belong in types/ (одна пара на операцию) */
export const ENTITY_CREATE_SCHEMA = z.object({
	[F.CLIENT]: z.string().min(1, { message: msg("errors.client.required") }),
	[F.STATUS]: z.enum(["PENDING", "CONFIRMED"]),
	[F.PAX]: z.number().min(1)
});

types/[entity-name]-create-form.types.ts

import type { FieldValues } from "react-hook-form";
import { z } from "zod";
// только import type — в рантайме зависимость schema → form.types односторонняя
import type { ENTITY_CREATE_SCHEMA } from "../schema";

export const ENUM_FORM_ENTITY_CREATE = {
	CLIENT: "client",
	STATUS: "status",
	PAX: "pax"
} as const;

export type ENUM_FORM_ENTITY_CREATE_TYPE =
	(typeof ENUM_FORM_ENTITY_CREATE)[keyof typeof ENUM_FORM_ENTITY_CREATE];

export type TEntityCreateSchema = z.infer<typeof ENTITY_CREATE_SCHEMA> &
	FieldValues;

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].interface.ts

import type { IPaginationRequest, IPaginationResponse } from "@/shared/types";

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;
}

export type TEntitiesPage = IPaginationResponse<IEntity>;
export interface IEntitiesQuery extends IPaginationRequest {}