From e166a6ec4600982dea15503501c1f79964ddd950 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 23 May 2026 17:23:39 +0000 Subject: [PATCH] refactor(arch): optimize architectures headers for deterministic Agent parsing Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com> --- architectures/agentic-architecture/readme.md | 4 +- .../backend-for-frontend/data-flow.md | 2 +- .../backend-for-frontend/folder-structure.md | 4 +- .../implementation-guide.md | 2 +- architectures/backend-for-frontend/readme.md | 8 ++-- architectures/clean-architecture/readme.md | 14 +++--- architectures/cqrs/readme.md | 10 ++--- .../implementation-guide.md | 2 +- architectures/domain-driven-design/readme.md | 10 ++--- .../implementation-guide.md | 6 +-- .../event-driven-architecture/readme.md | 10 ++--- .../event-driven-architecture/trade-offs.md | 4 +- .../event-sourcing/implementation-guide.md | 2 +- architectures/event-sourcing/readme.md | 10 ++--- architectures/feature-sliced-design/readme.md | 44 +++++++++---------- .../hexagonal-architecture/readme.md | 4 +- architectures/micro-frontends/data-flow.md | 2 +- .../micro-frontends/folder-structure.md | 2 +- .../micro-frontends/implementation-guide.md | 4 +- architectures/micro-frontends/readme.md | 10 ++--- architectures/micro-frontends/trade-offs.md | 2 +- .../microkernel-architecture/readme.md | 4 +- .../microservices/implementation-guide.md | 2 +- architectures/microservices/readme.md | 8 ++-- architectures/model-view-controller/readme.md | 44 +++++++++---------- .../implementation-guide.md | 2 +- .../monolithic-architecture/readme.md | 10 ++--- architectures/readme.md | 34 +++++++------- architectures/serverless/readme.md | 12 ++--- .../space-based-architecture/data-flow.md | 6 +-- .../space-based-architecture/readme.md | 10 ++--- 31 files changed, 144 insertions(+), 144 deletions(-) diff --git a/architectures/agentic-architecture/readme.md b/architectures/agentic-architecture/readme.md index 3c0fef7..71aca60 100644 --- a/architectures/agentic-architecture/readme.md +++ b/architectures/agentic-architecture/readme.md @@ -10,7 +10,7 @@ last_updated: 2026-04-17 # 🤖 Agentic Architecture (AI Agent Orchestration) Production-Ready Best Practices -# Context & Scope +# 🎯 Context & Scope - **Primary Goal:** Document and execute the best practices for AI Agent Orchestration and Multi-Agent Systems. - **Target Tooling:** AI Agents and Human Developers. - **Tech Stack Version:** Agnostic @@ -64,7 +64,7 @@ Agentic Architecture emphasizes the decomposition of monolithic tasks into granu --- -## 1. Monolithic Agent State Management +## 🚧 1. Monolithic Agent State Management ### ❌ Bad Practice ```typescript diff --git a/architectures/backend-for-frontend/data-flow.md b/architectures/backend-for-frontend/data-flow.md index 21fa2ca..d99e61b 100644 --- a/architectures/backend-for-frontend/data-flow.md +++ b/architectures/backend-for-frontend/data-flow.md @@ -42,7 +42,7 @@ sequenceDiagram deactivate MobileBFF ``` -## Core Principles +## 🧱 Core Principles 1. **Aggregation:** The BFF aggregates responses from multiple services to reduce the number of client-side requests. 2. **Formatting:** The BFF formats data precisely according to what the client needs, stripping out unnecessary fields to save bandwidth. diff --git a/architectures/backend-for-frontend/folder-structure.md b/architectures/backend-for-frontend/folder-structure.md index b5cd004..f49fe22 100644 --- a/architectures/backend-for-frontend/folder-structure.md +++ b/architectures/backend-for-frontend/folder-structure.md @@ -14,7 +14,7 @@ last_updated: 2026-03-29 --- -## Architecture Diagram & Folder Tree +## 📐 Architecture Diagram & Folder Tree ```mermaid graph TD @@ -37,7 +37,7 @@ graph TD --- -## 1. Directory Blueprint +## 🚧 1. Directory Blueprint ### ❌ Bad Practice ```text diff --git a/architectures/backend-for-frontend/implementation-guide.md b/architectures/backend-for-frontend/implementation-guide.md index 1673592..1627815 100644 --- a/architectures/backend-for-frontend/implementation-guide.md +++ b/architectures/backend-for-frontend/implementation-guide.md @@ -14,7 +14,7 @@ last_updated: 2026-03-29 --- -## 1. Concurrent Downstream Calls +## 🚧 1. Concurrent Downstream Calls ### ❌ Bad Practice ```typescript diff --git a/architectures/backend-for-frontend/readme.md b/architectures/backend-for-frontend/readme.md index 490df6f..9e49217 100644 --- a/architectures/backend-for-frontend/readme.md +++ b/architectures/backend-for-frontend/readme.md @@ -16,11 +16,11 @@ last_updated: 2026-03-29 This engineering directive defines the **best practices** for the Backend-For-Frontend (BFF) architecture. This document is designed to ensure maximum scalability, security, and code quality when developing applications that require tailored APIs for different clients (e.g., web, mobile). -# Context & Scope +# 🎯 Context & Scope - **Primary Goal:** Provide strict architectural rules and practical patterns for creating specialized backend services dedicated to specific frontend applications. - **Description:** A pattern where a separate backend service is created for each specific frontend application or interface type, rather than having a single general-purpose API backend for all clients. -## 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) @@ -59,7 +59,7 @@ graph TD ``` -## Core Principles +## 🧱 Core Principles 1. **Client Focus:** Each BFF is built and maintained by the same team that builds the frontend client. 2. **Aggregation:** The BFF orchestrates and aggregates calls to various downstream microservices. @@ -67,7 +67,7 @@ graph TD --- -## 1. Single Universal API for All Clients +## 🚧 1. Single Universal API for All Clients ### ❌ Bad Practice ```typescript diff --git a/architectures/clean-architecture/readme.md b/architectures/clean-architecture/readme.md index da03253..e5e370b 100644 --- a/architectures/clean-architecture/readme.md +++ b/architectures/clean-architecture/readme.md @@ -15,18 +15,18 @@ last_updated: 2026-03-29 This engineering directive defines the **best practices** for Clean Architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications. -# Context & Scope +# 🎯 Context & Scope - **Primary Goal:** Provide strict architectural rules and practical patterns for creating scalable systems. - > [!IMPORTANT] > **Description:** A concept created by Robert C. Martin (Uncle Bob). It separates a project into concentric rings. The main rule is the Dependency Rule: dependencies MUST STRICTLY only point inward. -## 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. @@ -41,7 +41,7 @@ graph LR class Isolation,Boundaries,Decoupling default; ``` -## Architecture Diagram +## 📐 Architecture Diagram ```mermaid graph TD @@ -62,7 +62,7 @@ graph TD --- -## 1. ORM Models Bleeding into Domain +## 🚧 1. ORM Models Bleeding into Domain ### ❌ Bad Practice ```typescript @@ -111,7 +111,7 @@ Isolate your Domain models from any external libraries. Use Data Mapper patterns --- -## 2. Direct Infrastructure Injection into Use Cases +## 🚧 2. Direct Infrastructure Injection into Use Cases ### ❌ Bad Practice ```typescript @@ -154,7 +154,7 @@ export class UploadAvatarUseCase { --- -## 3. Fat Controllers Dictating Business Flow +## 🚧 3. Fat Controllers Dictating Business Flow ### ❌ Bad Practice ```typescript diff --git a/architectures/cqrs/readme.md b/architectures/cqrs/readme.md index 675e114..7a802dc 100644 --- a/architectures/cqrs/readme.md +++ b/architectures/cqrs/readme.md @@ -15,15 +15,15 @@ last_updated: 2026-03-29 --- This engineering directive defines the **best practices** for the CQRS (Command Query Responsibility Segregation) architecture. This document is designed to ensure maximum scalability, security, and code quality when developing enterprise-level applications. -# Context & Scope +# 🎯 Context & Scope - **Primary Goal:** Provide strict architectural rules and practical patterns for creating scalable systems. - **Description:** A powerful pattern where Commands (actions that mutate system data) are entirely decoupled from Queries (actions that only read data). -## 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. @@ -38,7 +38,7 @@ graph LR class Isolation,Boundaries,Decoupling default; ``` -## Architecture Diagram +## 📐 Architecture Diagram ```mermaid graph LR @@ -62,7 +62,7 @@ graph LR --- -## 1. Mixing Reads and Writes in a Monolithic Service +## 🚧 1. Mixing Reads and Writes in a Monolithic Service ### ❌ Bad Practice ```typescript diff --git a/architectures/domain-driven-design/implementation-guide.md b/architectures/domain-driven-design/implementation-guide.md index 40b8a48..c9c3249 100644 --- a/architectures/domain-driven-design/implementation-guide.md +++ b/architectures/domain-driven-design/implementation-guide.md @@ -28,7 +28,7 @@ classDiagram ### Rules - Ubiquitous language must be strictly used in code. -### 1. Anemic Domain Model +### 🚧 1. Anemic Domain Model ### ❌ Bad Practice ```typescript diff --git a/architectures/domain-driven-design/readme.md b/architectures/domain-driven-design/readme.md index 287d091..4b648ae 100644 --- a/architectures/domain-driven-design/readme.md +++ b/architectures/domain-driven-design/readme.md @@ -15,21 +15,21 @@ last_updated: 2026-03-22 --- Этот инженерный директив определяет **лучшие практики (best practices)** для архитектуры Domain-Driven Design. Данный документ спроектирован для обеспечения максимальной масштабируемости, безопасности и качества кода при разработке приложений корпоративного уровня. -# Context & Scope +# 🎯 Context & Scope - **Primary Goal:** Предоставить строгие архитектурные правила и практические паттерны для создания масштабируемых систем. - **Description:** A philosophy and design approach centered entirely around the business "Domain". The whole team communicates using a "Ubiquitous Language," and domains are split into Bounded Contexts. -## 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 @@ -50,7 +50,7 @@ graph TD --- -## 1. Anemic Domain Models +## 🚧 1. Anemic Domain Models ### ❌ Bad Practice ```typescript diff --git a/architectures/event-driven-architecture/implementation-guide.md b/architectures/event-driven-architecture/implementation-guide.md index eec807d..79addbf 100644 --- a/architectures/event-driven-architecture/implementation-guide.md +++ b/architectures/event-driven-architecture/implementation-guide.md @@ -45,7 +45,7 @@ classDiagram DomainEvent <-- EventPublisher ``` --- -## 1. Idempotent Consumers (Crucial) +## 🚧 1. Idempotent Consumers (Crucial) > [!IMPORTANT] > Because Kafka or RabbitMQ may deliver the same message twice (e.g., during a consumer rebalance), handlers must be purely idempotent. Processing the exact same `eventId` twice MUST NOT duplicate the business outcome (e.g., charging a credit card twice). @@ -93,7 +93,7 @@ Without tracking `eventId` locally, duplicate deliveries from the broker (due to ### 🚀 Solution Implementing an Idempotent Receiver pattern with a unique constraint on `eventId` ensures that duplicate events are safely ignored. Wrapping the deduplication check and the business logic within an atomic database transaction guarantees state consistency even under high concurrency. --- -## 2. The Transactional Outbox Pattern +## 🚧 2. The Transactional Outbox Pattern To solve the "Dual-Write Problem" (saving state to the DB and publishing to Kafka reliably), we use an Outbox table. If the application crashes after saving to the DB but before publishing to Kafka, the message is permanently lost. @@ -146,7 +146,7 @@ The Dual-Write Anti-Pattern occurs when an application attempts to update a data ### 🚀 Solution The Transactional Outbox pattern guarantees atomic operations. By saving the event to a local `outbox` table within the same DB transaction as the domain change, we achieve atomicity. A separate, reliable process (like a Debezium Connector or background poller) then reads the outbox table and guarantees "at-least-once" delivery to the broker. --- -## 3. Strictly Typed Schemas (Schema Registry) +## 🚧 3. Strictly Typed Schemas (Schema Registry) Microservices evolve independently. If a publisher changes the shape of a JSON event payload, all downstream subscribers will break. Always enforce a Schema Registry (Avro, Protobuf, JSON Schema) for all events. diff --git a/architectures/event-driven-architecture/readme.md b/architectures/event-driven-architecture/readme.md index cabcc7d..0dd0b4e 100644 --- a/architectures/event-driven-architecture/readme.md +++ b/architectures/event-driven-architecture/readme.md @@ -17,14 +17,14 @@ last_updated: 2026-03-29 --- This engineering directive contains strict architectural guidelines and 2026-grade patterns for using Event-Driven Architecture (EDA) to build highly scalable, decoupled, and fault-tolerant backend systems. -## Context & Scope +## 🎯 Context & Scope - **Primary Goal:** Provide a determinist structural blueprint for managing asynchronous communication across autonomous microservices or domains using event streams and message brokers. - **Target Tooling:** AI Agents (Cursor, Copilot) and Senior/Architect Developers. - **Tech Stack Version:** Agnostic (Kafka, RabbitMQ, AWS EventBridge, Redis Pub/Sub, Node.js, Spring Boot). > [!NOTE] > **Architectural Contract:** System components MUST NOT depend on one another synchronously for state mutations. Components merely emit events (Publish) and react to events (Subscribe) via an intermediary broker, maintaining strict decoupling. -## Specialized Modules (Map of Patterns) +## 🗺️ Map of Patterns (Specialized Modules) To deeply understand the nuances of EDA, consult the following specialized modules: - 📊 [**Data Flow:** Request and Event Lifecycle](./data-flow.md) @@ -43,7 +43,7 @@ To deeply understand the nuances of EDA, consult the following specialized modul | **Scalability** | Excellent (Easy to add new consumers) | Good (Requires load balancing) | | **Complexity** | High (Eventual consistency, tracking flows) | Low (Straightforward flows) | -## Architecture Diagram +## 📐 Architecture Diagram ```mermaid graph LR @@ -62,7 +62,7 @@ graph LR class Pub component; ``` -## Core Principles +## 🧱 Core Principles 1. **Asynchronous by Default:** Synchronous RPC (REST/gRPC) is restricted only to immediate read-queries or initial gateway ingress. All inter-service state mutations must occur asynchronously. 2. **Event Sourcing (Optional but Recommended):** State is derived from an immutable, append-only log of events rather than overwriting records in a database. @@ -74,7 +74,7 @@ graph LR Adhere to these EDA principles to establish a relentlessly scalable, highly-decoupled system ecosystem! 🚀 -## 1. Synchronous Blocking on Events +## 🚧 1. Synchronous Blocking on Events ### ❌ Bad Practice ```typescript diff --git a/architectures/event-driven-architecture/trade-offs.md b/architectures/event-driven-architecture/trade-offs.md index 24859c4..f02afc2 100644 --- a/architectures/event-driven-architecture/trade-offs.md +++ b/architectures/event-driven-architecture/trade-offs.md @@ -15,7 +15,7 @@ last_updated: 2026-03-29 --- This document outlines the high-level trade-offs associated with Event-Driven Architecture. EDA introduces incredible scalability and loose coupling but incurs extreme operational complexity, eventual consistency, and distributed debugging challenges. -## 1. High-Level Comparison +## 🚧 1. High-Level Comparison | 🌟 **Pros (Advantages)** | ⚠️ **Cons (Disadvantages)** | | ------------------------ | --------------------------- | @@ -25,7 +25,7 @@ This document outlines the high-level trade-offs associated with Event-Driven Ar | **Extensibility:** Adding a new feature (e.g., a new Notification Service) requires zero changes to the Publisher. | **Duplicate Events:** Brokers guarantee "at-least-once" delivery. Consumers MUST be strictly idempotent. | | **Polyglot Systems:** Microservices can be written in any language as long as they adhere to the broker protocol and schema. | **Dual-Write Problem:** Guaranteeing a local DB commit and a Kafka publish simultaneously requires the Outbox Pattern. | --- -## 2. Distributed Anti-Patterns +## 🚧 2. Distributed Anti-Patterns ### ❌ The "Distributed Monolith" **Symptom:** Microservices communicate via events, but they expect an immediate asynchronous response via a "reply queue" (RPC over Kafka). The system halts if the response event is not received within a timeout. diff --git a/architectures/event-sourcing/implementation-guide.md b/architectures/event-sourcing/implementation-guide.md index b01e51a..6d66ec3 100644 --- a/architectures/event-sourcing/implementation-guide.md +++ b/architectures/event-sourcing/implementation-guide.md @@ -14,7 +14,7 @@ last_updated: 2026-03-29 --- -## 1. Mutating Existing Events +## 🚧 1. Mutating Existing Events ### ❌ Bad Practice ```typescript diff --git a/architectures/event-sourcing/readme.md b/architectures/event-sourcing/readme.md index c8636cf..592f415 100644 --- a/architectures/event-sourcing/readme.md +++ b/architectures/event-sourcing/readme.md @@ -16,17 +16,17 @@ last_updated: 2026-03-29 This engineering directive defines the **best practices** for the Event Sourcing architecture. This document is designed to ensure maximum scalability, security, and code quality when developing applications that require a robust audit trail and complex state reconstruction. -# Context & Scope +# 🎯 Context & Scope - **Primary Goal:** Provide strict architectural rules and practical patterns for building systems where state is derived from an immutable sequence of events. - **Description:** A pattern where all changes to application state are stored as a sequence of events. Instead of storing just the current state of the data in a domain, use an append-only store to record the full series of actions taken on that data. -## 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 @@ -51,13 +51,13 @@ graph TD --- -## Core Principles +## 🧱 Core Principles 1. **Immutable Log:** Events are facts that happened in the past. They cannot be changed or deleted, only appended. 2. **Replayable State:** Any entity's current state can be fully reconstructed by replaying all its past events from the beginning. 3. **Decoupled Read/Write:** Often combined with CQRS, Event Sourcing naturally decouples the write model (Event Store) from the read models (Projections). -## 1. Mutating State Instead of Appending Events +## 🚧 1. Mutating State Instead of Appending Events ### ❌ Bad Practice ```typescript diff --git a/architectures/feature-sliced-design/readme.md b/architectures/feature-sliced-design/readme.md index bf6870f..9f69197 100644 --- a/architectures/feature-sliced-design/readme.md +++ b/architectures/feature-sliced-design/readme.md @@ -28,7 +28,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 +51,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 +76,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 +105,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 +126,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 +157,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 +178,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 +210,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 +238,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 +268,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 +301,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 +322,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 +346,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 +369,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 +389,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 +412,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 +439,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 +466,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 +491,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 +515,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 +547,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..686eb0d 100644 --- a/architectures/hexagonal-architecture/readme.md +++ b/architectures/hexagonal-architecture/readme.md @@ -9,7 +9,7 @@ last_updated: 2026-03-22 --- # 🛑 Hexagonal Architecture Production-Ready Best Practices -# Context & Scope +# 🎯 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 @@ -47,7 +47,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/data-flow.md b/architectures/micro-frontends/data-flow.md index 8d5e21d..1539cef 100644 --- a/architectures/micro-frontends/data-flow.md +++ b/architectures/micro-frontends/data-flow.md @@ -18,7 +18,7 @@ This document defines strict rules for the data lifecycle, event handling, and r ## Request and Event Lifecycle -### 1. Synchronous Global Communication (Anti-Pattern) +### 🚧 1. Synchronous Global Communication (Anti-Pattern) #### ❌ Bad Practice ```javascript diff --git a/architectures/micro-frontends/folder-structure.md b/architectures/micro-frontends/folder-structure.md index 2e5133a..5d2cc9e 100644 --- a/architectures/micro-frontends/folder-structure.md +++ b/architectures/micro-frontends/folder-structure.md @@ -18,7 +18,7 @@ This document defines strict rules for the directory structure and logical layer ## Directory Layout Rules -### 1. Monorepo vs Polyrepo Constraints +### 🚧 1. Monorepo vs Polyrepo Constraints #### ❌ Bad Practice ```text diff --git a/architectures/micro-frontends/implementation-guide.md b/architectures/micro-frontends/implementation-guide.md index c2c37fb..39f5d26 100644 --- a/architectures/micro-frontends/implementation-guide.md +++ b/architectures/micro-frontends/implementation-guide.md @@ -18,7 +18,7 @@ This document defines practical implementation patterns and anti-patterns in the ## 2026 Code Patterns & Anti-patterns -### 1. Tight Routing Coupling (Hardcoded URLs) +### 🚧 1. Tight Routing Coupling (Hardcoded URLs) #### ❌ Bad Practice ```javascript @@ -48,7 +48,7 @@ function navigateToCart() { --- -### 2. Inconsistent Design and Shared UI +### 🚧 2. Inconsistent Design and Shared UI #### ❌ Bad Practice ```javascript diff --git a/architectures/micro-frontends/readme.md b/architectures/micro-frontends/readme.md index c8d0f1f..9fb0f33 100644 --- a/architectures/micro-frontends/readme.md +++ b/architectures/micro-frontends/readme.md @@ -16,17 +16,17 @@ 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 +# 🎯 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 +45,7 @@ graph LR --- -## 1. Global State Coupling +## 🚧 1. Global State Coupling ### ❌ Bad Practice ```javascript @@ -84,7 +84,7 @@ Communication between micro-frontends must be asynchronous and event-driven. Usi --- -## Architecture Diagram +## 📐 Architecture Diagram ```mermaid graph TD diff --git a/architectures/micro-frontends/trade-offs.md b/architectures/micro-frontends/trade-offs.md index 72787f2..d996b52 100644 --- a/architectures/micro-frontends/trade-offs.md +++ b/architectures/micro-frontends/trade-offs.md @@ -18,7 +18,7 @@ This document defines the pros, cons, and system constraints in the Micro-fronte ## Evaluated Pros & Cons -### 1. Excessive Dependency Duplication +### 🚧 1. Excessive Dependency Duplication #### ❌ Bad Practice ```javascript diff --git a/architectures/microkernel-architecture/readme.md b/architectures/microkernel-architecture/readme.md index 20fbc2e..61e1371 100644 --- a/architectures/microkernel-architecture/readme.md +++ b/architectures/microkernel-architecture/readme.md @@ -12,7 +12,7 @@ last_updated: 2026-04-18 [🏠 На главную](../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/implementation-guide.md b/architectures/microservices/implementation-guide.md index 76b9b77..a6304c5 100644 --- a/architectures/microservices/implementation-guide.md +++ b/architectures/microservices/implementation-guide.md @@ -24,7 +24,7 @@ classDiagram Gateway --> Service : RPC/HTTP ``` -## 1. Synchronous Cascading Calls +## 🚧 1. Synchronous Cascading Calls ### ❌ Bad Practice ```typescript diff --git a/architectures/microservices/readme.md b/architectures/microservices/readme.md index f7cad4d..7a0ab1d 100644 --- a/architectures/microservices/readme.md +++ b/architectures/microservices/readme.md @@ -15,10 +15,10 @@ 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 +# 🎯 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) @@ -33,7 +33,7 @@ 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. @@ -58,7 +58,7 @@ graph LR class A,B,C default; ``` -## 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..c4f8dfb 100644 --- a/architectures/model-view-controller/readme.md +++ b/architectures/model-view-controller/readme.md @@ -15,7 +15,7 @@ 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 +# 🎯 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 +54,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 +99,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 +137,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 +167,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 +195,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 +221,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 +250,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 +279,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 +310,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 +336,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 +364,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 +390,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 +412,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 +440,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 +470,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 +500,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 +523,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 +547,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 +581,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 +613,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/implementation-guide.md b/architectures/monolithic-architecture/implementation-guide.md index bc465e8..cd80f29 100644 --- a/architectures/monolithic-architecture/implementation-guide.md +++ b/architectures/monolithic-architecture/implementation-guide.md @@ -27,7 +27,7 @@ classDiagram ### Rules - Adopt Modular Monolith principles over time. -### 1. Tight Coupling via Global State +### 🚧 1. Tight Coupling via Global State ### ❌ Bad Practice ```typescript diff --git a/architectures/monolithic-architecture/readme.md b/architectures/monolithic-architecture/readme.md index f52bad6..ae1c52f 100644 --- a/architectures/monolithic-architecture/readme.md +++ b/architectures/monolithic-architecture/readme.md @@ -15,10 +15,10 @@ last_updated: 2026-03-22 --- Этот инженерный директив определяет **лучшие практики (best practices)** для архитектуры Monolithic Architecture. Данный документ спроектирован для обеспечения максимальной масштабируемости, безопасности и качества кода при разработке приложений корпоративного уровня. -# Context & Scope +# 🎯 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) @@ -34,7 +34,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 +53,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..5e97b88 100644 --- a/architectures/readme.md +++ b/architectures/readme.md @@ -12,7 +12,7 @@ last_updated: 2026-03-29 [🏠 На главную](../README.md) -# Context & Scope +# 🎯 Context & Scope - **Primary Goal:** Establish definitive rules and best practices for system design and architecture. - **Target Tooling:** Cursor, Windsurf, Antigravity. - **Tech Stack Version:** Agnostic @@ -64,7 +64,7 @@ Don't know where to start? Here are a few golden rules: Below are the most popular architectural patterns along with examples, tips, technology stacks, and their logos. A Folder Tree is provided for each to give you a deep understanding of its structure. --- -### 1. Feature-Sliced Design (FSD) +### 🚧 1. Feature-Sliced Design (FSD) FSD Logo **Description:** A modern architectural methodology for Frontend applications. It separates code by business meaning (features) and technical layers. It ensures strict unidirectional isolation. @@ -109,7 +109,7 @@ src/ - **Tools/Libraries:** Redux Toolkit, Zustand, React Router. --- -### 2. Clean Architecture +### 🚧 2. Clean Architecture [![Clean Arch](https://img.shields.io/badge/Clean_Architecture-black?style=flat-square)](#) > [!IMPORTANT] @@ -149,7 +149,7 @@ src/ - **Tools/Libraries:** ORMs (TypeORM, Prisma). --- -### 3. MVC (Model-View-Controller) +### 🚧 3. MVC (Model-View-Controller) [![MVC](https://img.shields.io/badge/Pattern-MVC-blue?style=flat-square)](#) **Description:** The classic design pattern for user-facing applications. It separates data logic (`Model`), presentation (`View`), and user action handling (`Controller`). @@ -188,7 +188,7 @@ src/ - **Patterns / Principles:** Active Record, REST, DRY. --- -### 4. Microservices +### 🚧 4. Microservices Microservices **Description:** Breaking down a giant monolithic system into small, independent pieces, each handling its own business capability. Each service has its own Database and communicates via REST, gRPC, or events. @@ -232,7 +232,7 @@ microservices-cluster/ - **Tools:** Docker, Kubernetes, gRPC. --- -### 5. Hexagonal Architecture (Ports & Adapters) +### 🚧 5. Hexagonal Architecture (Ports & Adapters) [![Hexagonal](https://img.shields.io/badge/Ports_&_Adapters-purple?style=flat-square)](#) **Description:** A logical evolution of Clean Architecture. The core of the system is isolated from specific technologies. All interaction with databases, UI, and side-effects happens through "Ports" (Interfaces), satisfying via "Adapters" (Implementations). @@ -274,7 +274,7 @@ src/ - **Patterns / Principles:** SOLID, Dependency Inversion (D in SOLID), Adapter. --- -### 6. DDD (Domain-Driven Design) +### 🚧 6. DDD (Domain-Driven Design) [![DDD](https://img.shields.io/badge/Architecture-DDD-darkred?style=flat-square)](#) **Description:** A philosophy and design approach centered entirely around the business "Domain". The whole team communicates using a "Ubiquitous Language," and domains are split into `Bounded Contexts`. @@ -315,7 +315,7 @@ src/ - **Patterns / Principles:** Bounded Contexts, Value Objects, Aggregates. --- -### 7. Event-Driven Architecture (EDA) +### 🚧 7. Event-Driven Architecture (EDA) Kafka Logo RabbitMQ **Description:** System components know nothing about each other (Low Coupling). They merely "publish" events and "subscribe" to them, reacting asynchronously. Ideal for high-load, highly-scalable backend systems. @@ -354,7 +354,7 @@ src/ - **Patterns / Principles:** Pub/Sub, Async Communication, Event Sourcing. --- -### 8. Serverless (Function-as-a-Service / FaaS) +### 🚧 8. Serverless (Function-as-a-Service / FaaS) AWS GCP **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, executed only via triggers. You pay solely for compute execution time. @@ -392,7 +392,7 @@ project-functions/ - **Patterns / Principles:** Backend-as-a-Service (BaaS), Vendor Lock-in (use cautiously). --- -### 9. Monolithic Architecture +### 🚧 9. Monolithic Architecture [![Monolithic](https://img.shields.io/badge/Architecture-Monolithic-brown?style=flat-square)](#) **Description:** The entire system components (Database, Message Queues, Business Logic, APIs) are deployed and operated from a single codebase on a single server. This is the optimal start for startups to avoid unnecessary complexity upfront. @@ -430,7 +430,7 @@ monolith-app/ - **Patterns / Principles:** Three-Tier Architecture, KISS, YAGNI. --- -### 10. CQRS (Command Query Responsibility Segregation) +### 🚧 10. CQRS (Command Query Responsibility Segregation) [![CQRS](https://img.shields.io/badge/Pattern-CQRS-teal?style=flat-square)](#) **Description:** A powerful pattern where Commands (actions that mutate system data) are entirely decoupled from Queries (actions that only read data). This separation enables extremely sophisticated load distribution. @@ -475,7 +475,7 @@ src/ --- -### 11. Micro-frontends +### 🚧 11. Micro-frontends [![Micro-frontends](https://img.shields.io/badge/Architecture-Micro--frontends-orange?style=flat-square)](#) **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, making scaling enterprise frontends deterministic. @@ -518,7 +518,7 @@ workspace/ --- -### 12. Event Sourcing +### 🚧 12. Event Sourcing [![Event Sourcing](https://img.shields.io/badge/Architecture-Event_Sourcing-darkgreen?style=flat-square)](#) **Description:** A pattern where all changes to application state are stored as a sequence of events. Instead of storing just the current state of the data in a domain, use an append-only store to record the full series of actions taken on that data. @@ -561,7 +561,7 @@ src/ --- -### 13. Backend-For-Frontend (BFF) +### 🚧 13. Backend-For-Frontend (BFF) [![Backend-For-Frontend](https://img.shields.io/badge/Architecture-BFF-blue?style=flat-square)](#) **Description:** A pattern where a separate backend service is created for each specific frontend application or interface type, rather than having a single general-purpose API backend for all clients. This allows the backend to be optimized for the specific needs of the frontend. @@ -604,7 +604,7 @@ src/ --- -### 14. Space-Based Architecture +### 🚧 14. Space-Based Architecture [![Space-Based Architecture](https://img.shields.io/badge/Architecture-Space--Based-indigo?style=flat-square)](#) **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. @@ -649,7 +649,7 @@ src/ --- -### 15. Agentic Architecture (AI Agent Orchestration) +### 🚧 15. Agentic Architecture (AI Agent Orchestration) [![Agentic Architecture](https://img.shields.io/badge/Architecture-Agentic-black?style=flat-square)](#) **Description:** An architecture that orchestrates multiple specialized AI agents, distributing complex workloads to optimize token efficiency, reduce context window overflow, and ensure deterministic, resilient outcomes. @@ -693,7 +693,7 @@ src/ - **Patterns / Principles:** Orchestrator-Worker, Map-Reduce, Multi-Agent Systems. --- -### 16. Microkernel Architecture (Plugin Architecture) +### 🚧 16. Microkernel Architecture (Plugin Architecture) [![Microkernel Architecture](https://img.shields.io/badge/Architecture-Microkernel-purple?style=flat-square)](#) **Description:** An architecture that strictly isolates essential business rules (the Core) from volatile, domain-specific, or external-facing logic (the Plugins). It guarantees O(1) impact on the core when adding or modifying auxiliary features. diff --git a/architectures/serverless/readme.md b/architectures/serverless/readme.md index e9a7e89..7331caa 100644 --- a/architectures/serverless/readme.md +++ b/architectures/serverless/readme.md @@ -15,23 +15,23 @@ last_updated: 2026-03-29 Этот инженерный директив определяет **лучшие практики (best practices)** для архитектуры Serverless. Данный документ спроектирован для обеспечения максимальной масштабируемости, безопасности и качества кода при разработке приложений корпоративного уровня. -# Context & Scope +# 🎯 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 +51,7 @@ graph TD --- -## 1. The Monolithic Lambda (Fat Function) +## 🚧 1. The Monolithic Lambda (Fat Function) ### ❌ Bad Practice ```javascript @@ -94,7 +94,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/data-flow.md b/architectures/space-based-architecture/data-flow.md index f8c2976..5be1850 100644 --- a/architectures/space-based-architecture/data-flow.md +++ b/architectures/space-based-architecture/data-flow.md @@ -16,15 +16,15 @@ last_updated: 2026-03-29 This document describes the request and event lifecycle in a Space-Based Architecture. -## 1. Request Handling +## 🚧 1. Request Handling When a request enters the system, the API Gateway routes it to the Virtualized Middleware. The middleware then intelligently assigns the request to the appropriate Processing Unit based on the required operation and the partitioned data shard. -## 2. In-Memory Execution +## 🚧 2. In-Memory Execution The Processing Unit receives the request and interacts almost exclusively with the In-Memory Data Grid (IMDG). Because the data is held in memory, read and write operations occur at microsecond speeds. No synchronous calls are made to persistent storage. -## 3. Data Syncing +## 🚧 3. Data Syncing Modifications to the IMDG are captured and streamed via asynchronous Data Pumps. These background processes replicate the changes to a central Persistent Storage (Database). If a node fails, the data can be recovered from the persistent store to rehydrate the grid. diff --git a/architectures/space-based-architecture/readme.md b/architectures/space-based-architecture/readme.md index b0f14ac..08fd80f 100644 --- a/architectures/space-based-architecture/readme.md +++ b/architectures/space-based-architecture/readme.md @@ -16,17 +16,17 @@ 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 +# 🎯 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 +54,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