docs: excessive-entities page

[Solant]

Background

This is a reimagining of the previous MR #859 with previously discussed changes

Some questions before the review:

• I was trying to add a reasoning section about "How excessive entities can harm the project," but it appeared to be harder than I thought (without a good diff view and fs structure widget). Do you think it is needed regardless?
• I'm not 100% satisfied with the code examples I gave, because the majority of them are a bit stretched examples of thin clients. It would be great to have some kind of shared project example with appropriate usage of entities that doesn't require a significant amount of time to be understood. Maybe you have some kind of example?

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

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

[illright]

Thanks, this is a very lean article! Regarding your questions:

• Yeah, it would probably be quite difficult to properly illustrate the issue with excessive entities, but I did leave a suggestion with at least a brief mention of the issues
• Unfortunately, I don't know of any good example that we could point to :(

I'm also thinking that maybe we could mention the principle of providing a good abstraction to the upper layers, namely, not to store random pieces of UI in entities like FSD once recommended. It's the thing I mentioned in my talk at Podlodka, idk if you relate to it or not, let me know

[illright]

issue:

The entities layer in Feature-Sliced Design is the first layer that incorporates business logic

That's not entirely consistent with the rest of the docs, because we mention that it's okay for some business logic to exist in Shared if the size of that business logic doesn't justify a separate layer.

suggestion:

I'm not sure we need the part about how it's distinct from Shared (they are two different layers, after all), so maybe we can shorten to this:

Suggested change

	The entities layer in Feature-Sliced Design is the first layer that incorporates business logic, distinguishing it from the `shared` layer. Unlike the `model` segment, it is globally accessible (except by `shared`), making it reusable across the application. However, its global nature means changes can have a widespread impact, requiring careful design to avoid costly refactors.
	The entities layer in Feature-Sliced Design is one of the lower layers that's primarily for business logic. That makes it widely accessible — all layers except for Shared can access it. However, its global nature means changes to Entities can have a widespread impact, requiring careful design to avoid costly refactors.

[illright]

suggestion: let's also include a little "bridge" phrase between needing to be careful with the design of Entities and the issue of excessive entities, something like:

One of the most common issues that make the Entities layer problematic is an excess of entities. This can cause ambiguity like "should this file live in the entities, or should it be higher?" and frustration due to import restrictions like "I need this part of the entity in another entity, should I move it to Shared?".

[illright]

issue: when I was reading this part, I thought that this text is the advice on how to keep the Entities layer clean, but turns out that it's just an informational aside, and the actual advice is in the subsequent headings

suggestion: perhaps let's just make this an aside, that way those readers who already know about the distinction of thick vs thin clients could just skip it over:

Suggested change

	## How to keep `entities` layer clean
	To keep a maintainable `entities` layer, consider the following principles based on the application's data processing needs. Keep in mind that this classification is not strictly binary, as different parts of the same application may have “thin” or “thick” parts:
	- Thin Clients: These applications rely on the backend for most data processing. They often do not require an `entities` layer, as client-side business logic is minimal and involves only data retrieval.
	- Thick Clients: These handle significant client-side business logic, making them suitable candidates for the `entities` layer.
	It is acceptable for an application to lack an `entities` layer if it functions as a thin client. This simplifies the architecture and keeps the `entities` layer available for future scaling if needed.
	## How to keep `entities` layer clean
	To keep a maintainable `entities` layer, consider the following principles based on the application's data processing needs — it is acceptable for an application to not have an `entities` layer if it functions as a thin client. This simplifies the architecture and keeps the `entities` layer available for future scaling if needed.
	:::info[What are thick and thin clients?]
	_Thick_ vs. _thin client_ distinction refers to how the application processes data:
	- _Thin_ clients rely on the backend for most data processing. Client-side business logic is minimal and involves only exchanging data with the backend.
	- _Thick_ clients handle significant client-side business logic, making them suitable candidates for the `entities` layer.
	Keep in mind that this classification is not strictly binary, and different parts of the same application may be "thicker" or "thinner" clients.
	:::

[illright]

Although I kinda want to have the thick/thin client be the "0th principle" — like "do you even need the entities layer"

[illright]

issue: I think this also collides a bit with the guide for authentication, where we present the entities layer as one of the options for storing auth data

suggestion: let's simply recommend storing auth data in shared for simple cases (i.e. most cases)