@@ -18,8 +20,15 @@ last_updated: 2026-03-22
This engineering directive contains strict architectural guidelines and 20 practical patterns for using the Feature-Sliced Design methodology to build scalable and deterministic Frontend applications.
+## 🎯 Context & Scope
+- **Primary Goal:** Document and execute the best practices for the Feature-Sliced Design pattern.
+- **Target Tooling:** AI Agents and Human Developers.
+- **Tech Stack Version:** Agnostic
+
+
+
-### Structural Comparison: Feature-Sliced Design vs Clean Architecture
+### ⚖️ Structural Comparison: Feature-Sliced Design vs Clean Architecture
| Feature | Feature-Sliced Design (FSD) | Clean Architecture |
| :--- | :--- | :--- |
@@ -28,7 +37,7 @@ This engineering directive contains strict architectural guidelines and 20 pract
| **Learning Curve** | High (Strict structural rules) | High (Abstract concepts) |
| **Scalability** | Excellent for large frontend teams | Excellent for complex enterprise backends |
-## Architecture Diagram
+## 📐 Architecture Diagram
```mermaid
graph TD
@@ -51,12 +60,12 @@ graph TD
class Widgets component;
```
-## Map of Patterns
+## 🗺️ Map of Patterns
- 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md)
- 📁 [**Folder Structure:** Layering publisher/subscriber logic](./folder-structure.md)
- ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md)
- 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md)
-## 1. Unidirectional Dependency Rule
+## 🚧 1. Unidirectional Dependency Rule
### ❌ Bad Practice
```typescript
@@ -76,7 +85,7 @@ import { Button } from 'shared/ui/button';
### 🚀 Solution
Layers must import modules exclusively from layers located strictly lower in the hierarchy: `app` -> `pages` -> `widgets` -> `features` -> `entities` -> `shared`.
---
-## 2. Cross-Slice Imports Within the Same Layer
+## 🚧 2. Cross-Slice Imports Within the Same Layer
### ❌ Bad Practice
```typescript
@@ -105,7 +114,7 @@ const ProductWidget = () => (
> [!IMPORTANT]
> Interaction between slices at the same level MUST occur through composition at higher layers (`widgets`, `pages`) or via global patterns (Global State, Event Bus).
---
-## 3. Public API Encapsulation (Bypassing Public API)
+## 🚧 3. Public API Encapsulation (Bypassing Public API)
### ❌ Bad Practice
```typescript
@@ -126,7 +135,7 @@ import { UserCard, fetchUser } from 'entities/user';
### 🚀 Solution
Every slice must have an entry point `index.ts` (Public API) that explicitly exports only what is intended for external use (Contract). All other files are considered strictly internal/private.
---
-## 4. Separation of Business Logic (Entity vs Feature)
+## 🚧 4. Separation of Business Logic (Entity vs Feature)
### ❌ Bad Practice
```typescript
@@ -157,7 +166,7 @@ export const LikeButton = ({ articleId }) => {
### 🚀 Solution
Separate the structure of the entity (`entities`) from user business actions (`features`). Integrate features into entities via render-props or React slots at the widgets layer.
---
-## 5. Domain Specifics in the Shared Layer
+## 🚧 5. Domain Specifics in the Shared Layer
### ❌ Bad Practice
```typescript
@@ -178,7 +187,7 @@ import { Button } from 'shared/ui/button';
### 🚀 Solution
The `shared` layer contains purely infrastructural code, reusable dumb components (UI-kit), and helpers, completely abstracted from the project's business knowledge.
---
-## 6. Area of Responsibility for Pages (Thick Pages)
+## 🚧 6. Area of Responsibility for Pages (Thick Pages)
### ❌ Bad Practice
```typescript
@@ -210,7 +219,7 @@ export const ProductPage = () => {
### 🚀 Solution
Delegate business logic and state management to `widgets` and `features`. The page (`pages`) is responsible for routing, SEO tags, and composing major blocks into the layout.
---
-## 7. Arbitrary Segment Structure Inside a Slice
+## 🚧 7. Arbitrary Segment Structure Inside a Slice
### ❌ Bad Practice
```typescript
@@ -238,7 +247,7 @@ features/auth-user/
### 🚀 Solution
Standard FSD segments must be applied exclusively within each slice: `ui` (JSX/components), `model` (state, hooks), `api` (network connectors), `lib` (helpers), `config` (variables/constants).
---
-## 8. Root App Component Architecture (God Object App)
+## 🚧 8. Root App Component Architecture (God Object App)
### ❌ Bad Practice
```typescript
@@ -268,7 +277,7 @@ export const App = () => (
### 🚀 Solution
Session business states are outsourced to `entities/session` or `features`. The `app` layer combines global configurations (Redux, QueryClient, DI Containers), global styles, and the routing tree.
---
-## 9. Global Store (Centralized State Management)
+## 🚧 9. Global Store (Centralized State Management)
### ❌ Bad Practice
```typescript
@@ -301,7 +310,7 @@ const store = configureStore({
### 🚀 Solution
Each slice sets up its own chunk of state locally in `model/slice.ts`, exporting the Reducer via the Public API. The root store in `app/store` simply composes them together.
---
-## 10. Deep Relative Imports
+## 🚧 10. Deep Relative Imports
### ❌ Bad Practice
```typescript
@@ -322,7 +331,7 @@ import { Button } from '@/shared/ui/button'; // Optionally via alias
### 🚀 Solution
Configure absolute path aliases in `tsconfig.json`. Apply them when importing across cross-layers and slices. Relative paths (`./`, `../`) are strictly allowed only within the boundaries of a single slice.
---
-## 11. Type Contract Encapsulation Leaks
+## 🚧 11. Type Contract Encapsulation Leaks
### ❌ Bad Practice
```typescript
@@ -346,7 +355,7 @@ export type { UserDTO } from './model/types';
### 🚀 Solution
Business types are declared uniquely in the `model` or `api` segment of the respective domain slice (`entities`, `features`) and are exposed externally exclusively through its root `index.ts`.
---
-## 12. Globalizing Local Configuration Constants
+## 🚧 12. Globalizing Local Configuration Constants
### ❌ Bad Practice
```typescript
@@ -369,7 +378,7 @@ import { MAX_MESSAGE_LENGTH } from '../config/constants';
### 🚀 Solution
Exploit the `config` segment to stockpile isolated constants, limits, and locales particular to a feature. Genuine global constants are kept in `shared/config`.
---
-## 13. Component Testing by Bypassing Public API
+## 🚧 13. Component Testing by Bypassing Public API
### ❌ Bad Practice
```typescript
@@ -389,7 +398,7 @@ import { AuthFeature } from 'features/auth';
### 🚀 Solution
Write tests for features and entities by importing their behaviors entirely via the Public API layer (`index.ts`). For test mocks, fashion an isolated `testing.ts` endpoint adjacent to the Public API.
---
-## 14. Domain Object Mixing (God Entity Objects)
+## 🚧 14. Domain Object Mixing (God Entity Objects)
### ❌ Bad Practice
```typescript
@@ -412,7 +421,7 @@ entities/payment/ // Financial endpoints and transactional ledgers
### 🚀 Solution
Each `entities` slice correlates to a rigorous and indivisible domain scope. Eliminate the architecting of "God Entities". Propel horizontal application scalability by shattering monoliths into manageable micro-domains.
---
-## 15. Hardwired Local Routing in an Isolated Slice
+## 🚧 15. Hardwired Local Routing in an Isolated Slice
### ❌ Bad Practice
```typescript
@@ -439,7 +448,7 @@ export const UserCard = ({ onNavigate }: Props) => (
### 🚀 Solution
Construct features and entities to operate Routing-Agnostic. They do not orchestrate route changes—they relay Event-triggers (Callbacks). Segregate routing mechanisms at the `pages` or `app/providers` layer.
---
-## 16. Polluting External Dependencies (Third-party Coupling)
+## 🚧 16. Polluting External Dependencies (Third-party Coupling)
### ❌ Bad Practice
```typescript
@@ -466,7 +475,7 @@ import { formatDate } from 'shared/lib/date';
### 🚀 Solution
Encase external Utility and API libraries behind an Adapter pattern explicitly at the `shared/lib` or `shared/api` strata. Export solely an encapsulated facet, concealing the underlying vendor details from feature modules.
---
-## 17. Fragmenting System Networking Errors
+## 🚧 17. Fragmenting System Networking Errors
### ❌ Bad Practice
```typescript
@@ -491,7 +500,7 @@ apiClient.interceptors.response.use(res => res, err => {
### 🚀 Solution
Engineer top-level Interceptor filters (Axios object overrides, Fetch API wrappers) exactly within the `shared/api` segment. Constrain localized feature handling strictly to discrete business-tier violations (e.g., "Bad format", HTTP 400).
---
-## 18. Abstraction Degradation in Slice Naming Conventions
+## 🚧 18. Abstraction Degradation in Slice Naming Conventions
### ❌ Bad Practice
```typescript
@@ -515,7 +524,7 @@ widgets/header-navigation/
### 🚀 Solution
Employ discernible industry nouns for `entities` and `widgets`. Utilize strictly descriptive business processes (Action-names) for defining `features`. Ultimately, slices must act as self-documenting assets based merely on title assignments.
---
-## 19. Misplaced Global Providers/HOCs Integrations
+## 🚧 19. Misplaced Global Providers/HOCs Integrations
### ❌ Bad Practice
```typescript
@@ -547,7 +556,7 @@ export const AppLayer = () => (
### 🚀 Solution
Any foundational systems (Theme logic, i18n, Central Redux Store, React Query Client mounts) are stringently dictated to execute out of `app/providers` globally exported via single orchestrator element (`
`).
---
-## 20. Engineering the Widgets Payload (Orchestration Scope)
+## 🚧 20. Engineering the Widgets Payload (Orchestration Scope)
### ❌ Bad Practice
```typescript
diff --git a/architectures/hexagonal-architecture/readme.md b/architectures/hexagonal-architecture/readme.md
index 236bbe3..9a26e2b 100644
--- a/architectures/hexagonal-architecture/readme.md
+++ b/architectures/hexagonal-architecture/readme.md
@@ -9,7 +9,9 @@ last_updated: 2026-03-22
---
# 🛑 Hexagonal Architecture Production-Ready Best Practices
-# Context & Scope
+[🏠 На главную](../readme.md)
+
+## 🎯 Context & Scope
- **Primary Goal:** Document and execute the best practices for the Hexagonal Architecture pattern.
- **Target Tooling:** AI Agents and Human Developers.
- **Tech Stack Version:** Agnostic
@@ -36,8 +38,15 @@ flowchart TD
C -->|Requires Port| D(Adapter)
D -->|Talks to| E[Database/External API]
+ %% Added Design Token Styles for Mermaid Diagrams
classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
- class A,B,C,D,E default;
+ classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+
+ class A default;
+ class B component;
+ class C component;
+ class D component;
+ class E default;
```
## 🚀 The Core Philosophy
@@ -47,7 +56,7 @@ All interactions with the DB, UI, or other systems happen through **Ports** (int
> **AI Constraint:** Always generate the Core Domain first. The Domain must have ZERO dependencies on frameworks or libraries (except language core features).
-## 1. Domain Logic Depending on External Adapters
+## 🚧 1. Domain Logic Depending on External Adapters
### ❌ Bad Practice
```typescript
diff --git a/architectures/micro-frontends/readme.md b/architectures/micro-frontends/readme.md
index c8d0f1f..313fc67 100644
--- a/architectures/micro-frontends/readme.md
+++ b/architectures/micro-frontends/readme.md
@@ -16,17 +16,19 @@ last_updated: 2026-03-22
This engineering directive defines the **best practices** for the Micro-frontends architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level frontend applications.
-# Context & Scope
+[🏠 На главную](../readme.md)
+
+## 🎯 Context & Scope
- **Primary Goal:** Provide strict architectural rules and practical patterns for breaking down a monolithic frontend into independent, deployable micro-applications.
- **Description:** An architectural style where independently deliverable frontend applications are composed into a greater whole. This enables multiple teams to work simultaneously without stepping on each other's toes.
-## Map of Patterns
+## 🗺️ Map of Patterns
- 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md)
- 📁 [**Folder Structure:** Layering logic](./folder-structure.md)
- ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md)
- 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md)
-## Core Principles
+## 🧱 Core Principles
1. **Independent Deployments:** Each micro-frontend must be deployable on its own without requiring a redeployment of the entire system.
2. **Technology Agnostic (Optional but powerful):** Different teams can use different frameworks (React, Vue, Angular) if necessary, though standardization is recommended for performance.
@@ -45,7 +47,7 @@ graph LR
---
-## 1. Global State Coupling
+## 🚧 1. Global State Coupling
### ❌ Bad Practice
```javascript
@@ -84,7 +86,7 @@ Communication between micro-frontends must be asynchronous and event-driven. Usi
---
-## Architecture Diagram
+## 📐 Architecture Diagram
```mermaid
graph TD
diff --git a/architectures/microkernel-architecture/readme.md b/architectures/microkernel-architecture/readme.md
index 20fbc2e..bb03d15 100644
--- a/architectures/microkernel-architecture/readme.md
+++ b/architectures/microkernel-architecture/readme.md
@@ -10,9 +10,9 @@ last_updated: 2026-04-18
# 🧩 Microkernel Architecture (Plugin Architecture) Production-Ready Best Practices
-[🏠 На главную](../README.md)
+[🏠 На главную](../readme.md)
-# Context & Scope
+## 🎯 Context & Scope
- **Primary Goal:** Document and strictly enforce best practices for Microkernel (Plugin) Architecture to ensure deterministic system extensibility.
- **Target Tooling:** AI Agents and Human Developers.
- **Tech Stack Version:** Agnostic
@@ -60,7 +60,7 @@ Microkernel Architecture strictly isolates essential business rules (the Core) f
---
-## 1. Core-Plugin Boundary Enforcement
+## 🚧 1. Core-Plugin Boundary Enforcement
### ❌ Bad Practice
```typescript
diff --git a/architectures/microservices/readme.md b/architectures/microservices/readme.md
index f7cad4d..4249c5e 100644
--- a/architectures/microservices/readme.md
+++ b/architectures/microservices/readme.md
@@ -15,16 +15,18 @@ last_updated: 2026-03-29
---
This engineering directive defines the **best practices** for the Microservices architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications.
-# Context & Scope
+
+[🏠 На главную](../readme.md)
+## 🎯 Context & Scope
- **Primary Goal:** Provide strict architectural rules and practical patterns for creating scalable systems.
- **Description:** Breaking down a giant monolithic system into small, independent pieces, each handling its own business capability. Each service has its own Database.
-## Map of Patterns
+## 🗺️ Map of Patterns
- 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md)
- 📁 [**Folder Structure:** Layering logic](./folder-structure.md)
- ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md)
- 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md)
-### Structural Comparison: Microservices vs SOA (Service-Oriented Architecture)
+### ⚖️ Structural Comparison: Microservices vs SOA (Service-Oriented Architecture)
| Feature | Microservices | SOA |
| :--- | :--- | :--- |
@@ -33,32 +35,34 @@ This engineering directive defines the **best practices** for the Microservices
| **Data Storage** | Database per service (Strict isolation) | Often shares data storage |
| **Coupling** | Loosely coupled | Moderately to tightly coupled |
-## Core Principles
+## 🧱 Core Principles
1. **Isolation & Testability:** Changing a single feature doesn't break the entire business process.
2. **Strict Boundaries:** Enforce rigid structural barriers between business logic and infrastructure.
3. **Decoupling:** Decouple how data is stored from how it is queried and displayed.
```mermaid
-graph LR
- Isolation[Isolation & Testability] --- Boundaries[Strict Boundaries]
- Boundaries --- Decoupling[Decoupling]
-
- classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
- class Isolation,Boundaries,Decoupling default;
-```
-
-
-
-```mermaid
-graph LR
- A[Isolation & Testability] --> B[Strict Boundaries]
- B --> C[Decoupling]
+graph TD
+ Client --> Gateway[API Gateway]
+ Gateway --> Auth[Auth Service]
+ Gateway --> Order[Order Service]
+ Gateway --> Pay[Payment Service]
+ Gateway --> Notif[Notification Service]
+
+ %% Added Design Token Styles for Mermaid Diagrams
classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
- class A,B,C default;
+ classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+ classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000;
+
+ class Order component;
+ class Client component;
+ class Auth component;
+ class Notif component;
+ class Gateway layout;
+ class Pay component;
```
-## 1. Shared Database Across Services
+## 🚧 1. Shared Database Across Services
### ❌ Bad Practice
```yaml
diff --git a/architectures/model-view-controller/readme.md b/architectures/model-view-controller/readme.md
index 878e662..aa0e05c 100644
--- a/architectures/model-view-controller/readme.md
+++ b/architectures/model-view-controller/readme.md
@@ -15,7 +15,9 @@ last_updated: 2026-03-22
---
This engineering directive defines the **best practices** for the MVC architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications.
-# Context & Scope
+[🏠 На главную](../readme.md)
+
+## 🎯 Context & Scope
- **Primary Goal:** Provide strict architectural rules and 20 practical patterns for creating scalable and deterministic MVC applications.
- **Target Tooling:** AI Agents (Cursor, Windsurf, Copilot, Antigravity) and Senior Developers.
- **Tech Stack Version:** Agnostic (Applicable to Node.js, NestJS, Express, Spring Boot, Django, ASP.NET, etc.).
@@ -54,12 +56,12 @@ graph TD
```
---
-## Map of Patterns
+## 🗺️ Map of Patterns
- 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md)
- 📁 [**Folder Structure:** Layering logic](./folder-structure.md)
- ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md)
- 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md)
-## 1. Fat Controllers (God Object Controller)
+## 🚧 1. Fat Controllers (God Object Controller)
### ❌ Bad Practice
```typescript
@@ -99,7 +101,7 @@ class UserController {
### 🚀 Solution
Adhere to the 'Thin Controllers' paradigm. Delegate all business scenarios to a dedicated Service Layer or aggregate domain models.
---
-## 2. Anemic Domain Model
+## 🚧 2. Anemic Domain Model
### ❌ Bad Practice
```typescript
@@ -137,7 +139,7 @@ class Order {
### 🚀 Solution
Encapsulate internal state mutations within the Model itself (Rich Model). External services must invoke the model's action methods via established contracts rather than overriding its data directly.
---
-## 3. Direct Model Exposure to View
+## 🚧 3. Direct Model Exposure to View
### ❌ Bad Practice
```typescript
@@ -167,7 +169,7 @@ class UserController {
### 🚀 Solution
Architecturally, it is mandatory to use DTO (Data Transfer Object) or ViewModel classes to isolate the transformation of the domain model into a client-safe structure (View / API).
---
-## 4. Complex Logic within Views
+## 🚧 4. Complex Logic within Views
### ❌ Bad Practice
```html
@@ -195,7 +197,7 @@ The View layer gets infected with business computations (calculating access righ
### 🚀 Solution
Export aggregated states for the presentation layer (View) via a Presenter (ViewModel). The View must remain 'Dumb', capable only of rendering boolean flags and arrays of DTOs.
---
-## 5. View Layer Initiating Database Transactions
+## 🚧 5. View Layer Initiating Database Transactions
### ❌ Bad Practice
```typescript
@@ -221,7 +223,7 @@ class UserController {
### 🚀 Solution
The dependency vector of the View layer is strictly unidirectional 'Top-Down', relying on data injected by the Controller. The View must not be aware of the existence of any Storage (Repositories/DBs).
---
-## 6. Global State and Singletons Bound to Models
+## 🚧 6. Global State and Singletons Bound to Models
### ❌ Bad Practice
```typescript
@@ -250,7 +252,7 @@ class Invoice {
### 🚀 Solution
Eliminate the use of global Singletons within the domain area. All external parameters or environment configurations must be passed to models transparently (explicit dependencies) via constructors or method arguments.
---
-## 7. Mixing Low-Level Routing with Controller Logic
+## 🚧 7. Mixing Low-Level Routing with Controller Logic
### ❌ Bad Practice
```typescript
@@ -279,7 +281,7 @@ router.get('/settings', userController.showSettings);
### 🚀 Solution
Leave routing to the framework or a dedicated Router layer. The Controller's job is to respond to an already formed method call with a prepared payload.
---
-## 8. Validation Rules Leaking into the Domain Layers
+## 🚧 8. Validation Rules Leaking into the Domain Layers
### ❌ Bad Practice
```typescript
@@ -310,7 +312,7 @@ class UserController {
### 🚀 Solution
Syntax and format validation (JSON Schema, DTO Validation) must be performed at the request processing layer (Gateways / Controllers). Services must receive strictly deterministic data formats.
---
-## 9. Lack of Dependency Injection in Controllers
+## 🚧 9. Lack of Dependency Injection in Controllers
### ❌ Bad Practice
```typescript
@@ -336,7 +338,7 @@ class OrderController {
### 🚀 Solution
Utilize the Dependency Injection (DI) pattern. Controllers request required services or repositories via interfaces (IoC Containers), guaranteeing the ability to hot-swap abstractions.
---
-## 10. Generating Raw HTML Strings Inside Controllers
+## 🚧 10. Generating Raw HTML Strings Inside Controllers
### ❌ Bad Practice
```typescript
@@ -364,7 +366,7 @@ class WelcomeController {
### 🚀 Solution
The Controller NEVER generates markup directly. Its functional contract is to pass data structures (ViewModel / JSON) to a standardized templating engine (Handlebars, React Server, EJS).
---
-## 11. God Models (Monolithic Bounded Contexts)
+## 🚧 11. God Models (Monolithic Bounded Contexts)
### ❌ Bad Practice
```typescript
@@ -390,7 +392,7 @@ class PdfGeneratorService { ... }
### 🚀 Solution
Decompose god models into focused aggregates within strict Bounded Contexts.
---
-## 12. View Layer Mutating Upstream State
+## 🚧 12. View Layer Mutating Upstream State
### ❌ Bad Practice
```typescript
@@ -412,7 +414,7 @@ The View mutates the Model's state, bypassing the Controller and failing to noti
### 🚀 Solution
The MVC pattern dictates that the View is merely a Read-only Projection of the current data. For mutations, the View must send an instruction to the Controller (HTTP Request, Event), which then authorizes the process.
---
-## 13. Hardwired Environment Secrets within Logic Code
+## 🚧 13. Hardwired Environment Secrets within Logic Code
### ❌ Bad Practice
```typescript
@@ -440,7 +442,7 @@ class BillingService {
### 🚀 Solution
Hardcoding any environment variables (Passwords, URLs, Tokens) in Controllers and Models is forbidden. All infrastructure configuration must be loaded from a specialized configuration provider.
---
-## 14. Blocking Main Thread in Standard Controllers
+## 🚧 14. Blocking Main Thread in Standard Controllers
### ❌ Bad Practice
```typescript
@@ -470,7 +472,7 @@ class ReportController {
### 🚀 Solution
Integrate Job systems (RabbitMQ, Redis Queues). The Controller must delegate resource-intensive tasks to background workers and immediately return HTTP 202 (Accepted).
---
-## 15. The "Repository" Abstraction Leak to View/Controller
+## 🚧 15. The "Repository" Abstraction Leak to View/Controller
### ❌ Bad Practice
```typescript
@@ -500,7 +502,7 @@ class DashboardController {
### 🚀 Solution
Shield the View and Controller layers from low-level I/O operations. Integrate Repository / Data Access Object (DAO) patterns.
---
-## 16. Exposing Sequent Database Identifiers (IDOR Threat)
+## 🚧 16. Exposing Sequent Database Identifiers (IDOR Threat)
### ❌ Bad Practice
```typescript
@@ -523,7 +525,7 @@ class TransactionResponse {
### 🚀 Solution
Translate internal physical database identifiers (Integers) into external string UUIDs or hashes before the Controller passes them to the View.
---
-## 17. Duplicating Core Invariants Inside Templates
+## 🚧 17. Duplicating Core Invariants Inside Templates
### ❌ Bad Practice
```typescript
@@ -547,7 +549,7 @@ Duplicating business system domain invariants. If the weight threshold changes t
> [!IMPORTANT]
> The Domain Model is the single "Source of Truth". The View MUST read pre-computed polymorphic state provided by the system.
---
-## 18. Side-Effects Orchestration Inside Controller Scope
+## 🚧 18. Side-Effects Orchestration Inside Controller Scope
### ❌ Bad Practice
```typescript
@@ -581,7 +583,7 @@ class SubscriptionController {
> [!IMPORTANT]
> Implement Domain Events Architectures (Pub/Sub brokers). The Controller is strictly responsible for initiating the "Payment complete" business event; dispatch logic MUST not block the response channel to the client.
---
-## 19. Fractured Exception Logging (Try-Catch Hell)
+## 🚧 19. Fractured Exception Logging (Try-Catch Hell)
### ❌ Bad Practice
```typescript
@@ -613,7 +615,7 @@ class ItemController {
### 🚀 Solution
Abstract the Error Handling procedure into framework-level Global Exception Handlers, standardizing the format of HTTP 4XX / 5XX error responses for the View.
---
-## 20. Overusing the Model Segment for Hardware Infrastructure (AWS, FS)
+## 🚧 20. Overusing the Model Segment for Hardware Infrastructure (AWS, FS)
### ❌ Bad Practice
```typescript
diff --git a/architectures/monolithic-architecture/readme.md b/architectures/monolithic-architecture/readme.md
index f52bad6..41848c7 100644
--- a/architectures/monolithic-architecture/readme.md
+++ b/architectures/monolithic-architecture/readme.md
@@ -15,16 +15,18 @@ last_updated: 2026-03-22
---
Этот инженерный директив определяет **лучшие практики (best practices)** для архитектуры Monolithic Architecture. Данный документ спроектирован для обеспечения максимальной масштабируемости, безопасности и качества кода при разработке приложений корпоративного уровня.
-# Context & Scope
+[🏠 На главную](../readme.md)
+
+## 🎯 Context & Scope
- **Primary Goal:** Предоставить строгие архитектурные правила и практические паттерны для создания масштабируемых систем.
- **Description:** The entire system components (Database, Message Queues, Business Logic, APIs) are deployed and operated from a single codebase on a single server.
-## Map of Patterns
+## 🗺️ Map of Patterns
- 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md)
- 📁 [**Folder Structure:** Layering logic](./folder-structure.md)
- ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md)
- 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md)
-### Structural Comparison: Monolithic Architecture vs Microservices
+### ⚖️ Structural Comparison: Monolithic Architecture vs Microservices
| Feature | Monolithic Architecture | Microservices |
| :--- | :--- | :--- |
@@ -34,7 +36,7 @@ last_updated: 2026-03-22
| **Complexity** | Lower initially, higher as it grows | Higher initially, manageable at scale |
| **Data Management** | Shared database | Database per service |
-## Architecture Diagram
+## 📐 Architecture Diagram
```mermaid
graph TD
@@ -53,13 +55,13 @@ graph TD
class Project layout;
```
-## Core Principles
+## 🧱 Core Principles
1. **Isolation & Testability:** Changing a single feature doesn't break the entire business process.
2. **Strict Boundaries:** Enforce rigid structural barriers between business logic and infrastructure.
3. **Decoupling:** Decouple how data is stored from how it is queried and displayed.
-## 1. Tightly Coupled Internal Modules (Spaghetti Code)
+## 🚧 1. Tightly Coupled Internal Modules (Spaghetti Code)
### ❌ Bad Practice
```typescript
diff --git a/architectures/readme.md b/architectures/readme.md
index 266a53a..6074cf0 100644
--- a/architectures/readme.md
+++ b/architectures/readme.md
@@ -10,7 +10,7 @@ last_updated: 2026-03-29
# Architecture Best Practices & Production-Ready Patterns
-[🏠 На главную](../README.md)
+[🏠 На главную](../readme.md)
# Context & Scope
- **Primary Goal:** Establish definitive rules and best practices for system design and architecture.
@@ -58,6 +58,7 @@ Don't know where to start? Here are a few golden rules:
- [Space-Based Architecture](./space-based-architecture/readme.md)
- [Serverless](./serverless/readme.md)
- [Agentic Architecture (AI Agent Orchestration)](./agentic-architecture/readme.md)
+- [Microkernel Architecture](./microkernel-architecture/readme.md)
## 🏆 Top 15 Best Architectural Approaches
diff --git a/architectures/serverless/readme.md b/architectures/serverless/readme.md
index e9a7e89..055780f 100644
--- a/architectures/serverless/readme.md
+++ b/architectures/serverless/readme.md
@@ -15,23 +15,25 @@ last_updated: 2026-03-29
Этот инженерный директив определяет **лучшие практики (best practices)** для архитектуры Serverless. Данный документ спроектирован для обеспечения максимальной масштабируемости, безопасности и качества кода при разработке приложений корпоративного уровня.
-# Context & Scope
+[🏠 На главную](../readme.md)
+
+## 🎯 Context & Scope
- **Primary Goal:** Предоставить строгие архитектурные правила и практические паттерны для создания масштабируемых систем.
- **Description:** Developers do not manage servers at all. The entire "server" consists of bite-sized pieces of business logic (functions/Lambdas) living in the cloud.
-## Map of Patterns
+## 🗺️ Map of Patterns
- 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md)
- 📁 [**Folder Structure:** Layering logic](./folder-structure.md)
- ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md)
- 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md)
-## Core Principles
+## 🧱 Core Principles
1. **Isolation & Testability:** Changing a single feature doesn't break the entire business process.
2. **Strict Boundaries:** Enforce rigid structural barriers between business logic and infrastructure.
3. **Decoupling:** Decouple how data is stored from how it is queried and displayed.
-## Architecture Diagram
+## 📐 Architecture Diagram
```mermaid
graph TD
@@ -51,7 +53,7 @@ graph TD
---
-## 1. The Monolithic Lambda (Fat Function)
+## 🚧 1. The Monolithic Lambda (Fat Function)
### ❌ Bad Practice
```javascript
@@ -94,7 +96,7 @@ Embrace the "Single Responsibility Principle" at the infrastructure level. Decom
---
-## 2. Stateful Execution Contexts
+## 🚧 2. Stateful Execution Contexts
### ❌ Bad Practice
```javascript
diff --git a/architectures/space-based-architecture/readme.md b/architectures/space-based-architecture/readme.md
index b0f14ac..b76a981 100644
--- a/architectures/space-based-architecture/readme.md
+++ b/architectures/space-based-architecture/readme.md
@@ -16,17 +16,19 @@ last_updated: 2026-03-29
This engineering directive defines the **best practices** for the Space-Based Architecture (SBA). This document is designed to ensure maximum scalability, security, and code quality when developing applications that require extreme high-performance and low-latency under unpredictable, fluctuating user loads.
-# Context & Scope
+[🏠 На главную](../readme.md)
+
+## 🎯 Context & Scope
- **Primary Goal:** Provide strict architectural rules and practical patterns for building systems that rely on distributed in-memory data grids to eliminate database bottlenecks.
- **Description:** A pattern designed to minimize the constraints of a central database by keeping state in an in-memory data grid. The architecture relies on "processing units" that independently execute logic and communicate with each other or the grid.
-## Map of Patterns
+## 🗺️ Map of Patterns
- 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md)
- 📁 [**Folder Structure:** Layering logic](./folder-structure.md)
- ⚖️ [**Trade-offs:** Pros, Cons, and System Constraints](./trade-offs.md)
- 🛠️ [**Implementation Guide:** Code patterns and Anti-patterns](./implementation-guide.md)
-## Architecture Diagram
+## 📐 Architecture Diagram
```mermaid
graph TD
@@ -54,14 +56,14 @@ graph TD
---
-## Core Principles
+## 🧱 Core Principles
1. **Database Bottleneck Elimination:** Traditional central databases act as a choke point during high load. SBA completely avoids synchronous DB writes in the critical request path.
2. **In-Memory Data Grid (IMDG):** The state is aggressively cached and maintained in an IMDG, providing microsecond access times for Processing Units.
3. **Independent Processing Units:** Microservices or components that contain business logic and operate over small shards of data, executing autonomously.
4. **Asynchronous Persistence:** The IMDG eventually syncs data back to a persistent store in the background, out of the hot path.
-## 1. Synchronous Database Writes in Processing Units
+## 🚧 1. Synchronous Database Writes in Processing Units
### ❌ Bad Practice
```typescript