docs: add guidance on when to create an entity

[dyakubovskiy]

Background

Русский:
Добавляет практические рекомендации по выделению сущностей (entities) на этапе масштабирования проекта. Рекомендации помогают избежать распространённых ошибок при проектировании архитектуры: преждевременного выделения сущностей или, наоборот, запоздалого рефакторинга.

English:
Adds practical recommendations for extracting entities during project scaling. The guidelines help avoid common architectural pitfalls: premature entity extraction or, conversely, delayed refactoring when the codebase has already become entangled.

Changelog

Русский:

1. Добавлены рекомендации на русском языке о критериях выделения сущностей при масштабировании
2. Добавлен перевод рекомендаций на английский язык
3. Описаны признаки для выделения отдельной сущности: стабильность доменной области, повторное использование в разных слоях, рост сложности бизнес-логики

English:

1. Added Russian-language recommendations on entity extraction criteria during scaling
2. Provided English translation of the recommendations
3. Described indicators for extracting a separate entity: domain stability, reuse across layers, and growing complexity of business logic

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
pr-fsd	✅ Ready (View Log)	Visit Preview	e2b2629

[illright]

The content is great, thank you! I agree with @Gaic4o that the diagram should perhaps be inserted as an image because it is unreadable when rendered by Docusaurus:

And I also think that the Reference section is not the best place to put advice. This documentation is structured by the Diataxis framework (https://diataxis.fr/), and we've been keeping advice mostly in Guides. Speaking of which, there is a guide about Excessive entities (Code smells & issues), and I have a feeling that this new section shares a lot of content with that guide, could we perhaps deduplicate and leave a link instead?

[dyakubovskiy]

I replaced the diagram with a Mermaid

[dyakubovskiy]

I replaced the diagram with a Mermaid one

[Stanislavsky69]

[RU]

Рекомендации по выявлению сущностей.

Сущность - объект предметной области, который отражает суть бизнеса. Отличительная черта сущности - его уникальность. При проектировании слоя entities в рамках FSD нужно сначала определиться с бизнесом, что есть сущность по его уникальности. Например, уникальный атрибут у заказа - номер, у товара - артикул. Иногда, есть данные, которых не хватает для однозначного определения сущности. Тогда нужно изучить структуру, которую отдает бэк и найти уникальный атрибут, например, id. Если и этого не хватает для однозначного определения сущности, то можно подумать об объекте в реально жизни. Может ли он обладать своей уникальностью?

Слой entities отражает ваши основные объекты и нуждается в проектировании на ранних этапах.

Пример:

Типичная задача.

Заголовок:
Реализовать фичу добавления пользователя в систему

Описание:

1. Обязательное поле ФИО
2. Обязательное поле Адрес проживания (город, улица, дом)
3. Обязательное поле год рождения
4. Новому пользователю назначается роль "менеджер" по умолчанию.

Первый пункт. Может ли ФИО говорить об уникальности? Нет.
Второй пункт. Может ли адрес проживания говорить об уникальности? Я бы сказал, что он может являться уникальным, но не гарантировать уникальность. Обратите внимание, что в требованиях нет индекса.
Третий пункт. Год рождения всегда не уникальный.
Четвертый пункт. У роли есть имя и набор доступов. У роли нет явных бизнес ориентированных атрибутов указывающих на ее уникальность. А раз нет, то мы
смотрим на технические атрибуты. У роли есть id и это значение инкрементное. Вывод: роль - сущность.

А что с пользователем? Если по бизнесу нет явных атрибутов указывающих на ее уникальность, а их нет, то мы смотрим на технические атрибуты. У пользователя как и у роли есть атрибут id. Вывод: пользователь - сущность.

Другой пример

Заголовок:
Реализовать возможность делится сформированным отчетом

Описание:

1. После создания отчета показывать уникальный ключ (хэш) в модальном окне
2. Добавить описание в модальное окно: "Ключ живет 30 минут. Вы можете поделится им с другим пользователем, чтобы он мог просмотреть отчет."

Второй пункт нас не интересует. Первый пункт нам говорит о том, что у отчета есть уникальный ключ, который характеризует его как сущность.

Не бойтесь общаться с бизнесом. Слой entities должен изменятся именно с изменениями в бизнесе.

Я рекомендую нарезать сущности сразу, чтобы избежать анемичной модели (https://en.wikipedia.org/wiki/Anemic_domain_model).

Важно! Это противоречит подходу с page first, потому что требует чуть больше времени и усилий.

[EN]

Recommendations for identifying entities.

An entity is a domain object that reflects the essence of a business. The distinguishing feature of an entity is its uniqueness. When designing the entities layer within the FSD framework, it is necessary to first determine the business and identify the entity based on its uniqueness. For example, the unique attribute of an order is its number, while the unique attribute of a product is its SKU. In some cases, there may be data that is insufficient to uniquely identify an entity. In such cases, it is necessary to examine the structure provided by the back-end and identify a unique attribute, such as an ID. If even this is insufficient to uniquely identify an entity, it may be necessary to consider the entity in real life and determine whether it possesses its own uniqueness.

The entities layer represents your primary objects and requires early design.

Example:

This is a typical task.

Title:
Implement the feature of adding a user to the system

Description:

1. Required field: Full Name
2. Required field: Address (city, street, house)
3. Required field: Year of Birth
4. The new user is assigned the "manager" role by default.

First point: Can the Full Name be considered unique? No.
Second point. Can the residential address speak about uniqueness? I would say that it can be unique, but it does not guarantee uniqueness. Please note that there is no index in the requirements.
Third point. The year of birth is always not unique.
Fourth point. The role has a name and a set of permissions. The role does not have any explicit business-oriented attributes that indicate its uniqueness. Since there are no such attributes, we look at the technical attributes. The role has an id, and this value is incremental. Therefore, the role is an entity.

What about the user? If there are no explicit business-oriented attributes that indicate its uniqueness, and there are none, then we look at the technical attributes. The user, like the role, has an id attribute. Therefore, the user is an entity.

Another example

Title:
Implement the ability to share a generated report

Description:

1. After creating a report, show the unique key (hash) in a modal window.
2. Add a description to the modal window: "The key is valid for 30 minutes. You can share it with another user so they can view the report."

We are not interested in the second point. The first point tells us that the report has a unique key that characterizes it as an entity.

Don't be afraid to communicate with the business. The entities layer should change with changes in the business.

I recommend slicing entities immediately to avoid an anemic model (https://en.wikipedia.org/wiki/Anemic_domain_model).

Important! This goes against the page first approach because it requires a little more time and effort.

[illright]

I still think this page should not be in the Reference, but rather, in Guides. It gives advice rather than describing definitions and base principles, as the reference should, in my opinion.

[Solant]

I got a read, I see good points how we can show proper usage of entities, but I am a bit concerned about a current state of this article:

• it is quite large and repeats itself a lot (in regards to business-management communication)
• examples are vue-specific, and it would be much better to show how to handle business logic in pure js (without react state and vue reactivity), as it might be hard for React developers to follow Vue example and vice-versa
• while text states that there should be a good reason to create an entity, in the examples there are couple of entities created straight from the DTO type, without any abstraction. so it looks like examples are trying to create an entity when it is not required (just for the sake of it), which can lead to leaky abstractions
• some paragraphs are repeating already existing pages from the documentation

[Gaic4o]

One concern about the entities/user example:

In real-world products, “User” is often a very broad umbrella concept, so readers might interpret this page as “put all user-related business logic into entities/user/api and entities/user/model.” Over time, this can turn entities/user into a dumping ground where more and more code accumulates, which may hurt maintainability.

With that in mind, I wanted to ask (carefully) whether there might be a better example than User, Customer, Order, Product etc.. for this section — or perhaps a better way to phrase it to avoid that interpretation.

Also, in larger domains, it’s common to either:

(a) modularize within the same slice by responsibility (e.g., splitting read/write operations and separating model concerns), for example:

entities/user/
  api/
    queries/      # read operations
    mutations/    # write operations
  model/
    permissions/
    ...

(b) or split by domain context into more specific entities or slice groups. For example:

entities/user/
  guide/
  profile/

It might be helpful to mention these evolution paths so readers don’t assume a single giant entities/user is always the intended direction.

Looking at the current example code, it seems like most of it follows a structure like this:

shared/
  api/
    client.ts         # infrastructure only
    types.ts

entities/
  user/
    api/
      user-api.ts     # API + mapping (~100 lines)
    model/
      types.ts
      use-user-permissions.ts  # business logic (~150 lines)
    index.ts

So I brought this up after thinking about it in that context.

[dyakubovskiy]

Taken into account and implemented in the new version. The file has been fully rewritten and moved from the reference section to guides — examples are now in React+TS and plain TypeScript without framework reactivity, repetitions are removed, the Approach A section is condensed with a link to the existing api-requests page, and architectural issues are fixed (entity type moved from api/ to model/, files renamed to reflect their contents).

[Solant]

I think the flow is a bit fragmented: some paragraphs have no text except the small code samples, and lists consisting of minimal synopses might not be enough for the reader to understand the idea behind the reasoning. So I suggest adding some reasoning/explanation

[Gaic4o]

I’m also sharing a few additional suggestions that may help make the document clearer overall.

source code was changed

[Gaic4o]

I think the topic of this document is good. When to Create an Entitys something people often struggle with when applying FSD, so I think it makes sense to cover it as a separate guide.

That said, some parts of the current content seem to overlap with the existing Excessive Entities document. It might be better to link to that document for the overlapping parts, and have this document focus more on what kinds of logic should be managed in the entities layer after an entity is introduced.

In practice, once the entities layer is introduced, it can often be unclear which logic belongs to the entity itself and which logic is closer to a specific feature or user scenario. From that perspective, I think explaining the boundary with the features layer would help readers understand the role of the entities layer more clearly.

[Gaic4o]

I read through the PR again, and I think some parts overlap with the existing Excessive Entities document.

In particular, the approach of using shared/api and the idea that the entities layer does not need to be added from the beginning are already covered in that document. So it might be better to link to it as a reference for those parts. Otherwise, the roles of the two documents may end up feeling somewhat overlapping.

Instead, I think this document could focus more on what criteria should be used to decide whether to create an entity, and what kinds of code should be managed together inside the entities layer once we decide to separate something as an entity.

What do you think?

[Gaic4o]

I also thought about the section that introduces Locality, Centralized API, and Domain API as three separate approaches.

I think it might be clearer to describe this as a recommended gradual flow rather than as three separate options. In practice, code usually starts locally in the pages layer. When it starts being reused across multiple pages, it can move to shared/api. Then, once business rules or domain responsibilities become clearer, it can move to entities/*.

With the current structure, readers might understand these as three approaches to choose from depending on the situation, rather than as steps that naturally build on each other. Presenting them as a gradual flow could make the document more aligned with the Local First principle and easier to follow.

What do you think?

[Gaic4o]

I also thought a bit about this part.

The current wording could read a bit strongly, as if other developers starting to copy the code naturally means the next step is to extract it into a shared module. However, in the From a custom architecture section of the official docs, it says that copy pasting is not architecturally wrong by itself, and that in some cases duplicating code can be more appropriate than abstracting it into a new reusable module.

So instead of framing this as a signal that the code should be extracted into a shared module, I think it might fit better with the tone of the official docs to describe it as a signal to check whether the same code is being repeated with the same intent in multiple places, and whether extracting it into a reusable module would actually be more appropriate.

What do you think?

[Gaic4o]

I think the formatDate example might not be necessary in this section. It seems clearly closer to a reusable utility function than a business entity, so it does not feel like a case where readers would really wonder whether it should belong in the entities layer.

For this document, I think it might be more helpful to use an example where the placement is actually a bit ambiguous. Otherwise, I think this example could also be removed.

What do you think?

[Gaic4o]

- Teams starting to work with FSD
- Small projects (fewer than ~10 screens)
- Projects with frequently changing business logic
- When it's unclear which entities have stabilized
....
## Approach 2: Domain API (`entities/*/api/`)

In this approach, each entity lives fully inside its own slice — including the API, DTO mapping, domain types, and business logic.

### When to Use

- Medium and large projects
- Teams experienced with FSD
- Projects where backend API stability matters
- Long-lived enterprise applications

I agree with the idea that shared/api can be a more practical option for small projects or for teams that are not yet familiar with FSD. If a team introduces the entities layer too early without being comfortable with FSD, the structure can become more complex and harder to manage consistently.

That said, I think the “fewer than 10 screens” criterion might be worth handling a bit carefully. Even if a project has only a small number of screens, there can still be cases where the same DTOs or API responses are reused across multiple pages, or where the same mapping logic starts appearing in several places. In those cases, it may be hard to decide based on project size alone.

So rather than focusing on the number of screens, I think it might feel more natural to explain this in terms of how the code is actually reused, whether the domain responsibility is clear, and whether the team can manage that layer consistently.

What do you think?