diff --git a/architectures/clean-architecture/data-flow.md b/architectures/clean-architecture/data-flow.md new file mode 100644 index 0000000..6919241 --- /dev/null +++ b/architectures/clean-architecture/data-flow.md @@ -0,0 +1,26 @@ +# Clean Architecture - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant User + participant Controller + participant UseCase + participant Entity + participant Repository + participant Database + + User->>Controller: HTTP Request + Controller->>UseCase: Execute Request DTO + UseCase->>Entity: Apply Business Rules + UseCase->>Repository: Fetch/Save Data + Repository->>Database: Query + Database-->>Repository: Result + Repository-->>UseCase: Entity + UseCase-->>Controller: Response DTO + Controller-->>User: HTTP Response +``` + +### Constraints +- Dependency rule always points inwards towards the domain. diff --git a/architectures/clean-architecture/folder-structure.md b/architectures/clean-architecture/folder-structure.md new file mode 100644 index 0000000..74d4a0f --- /dev/null +++ b/architectures/clean-architecture/folder-structure.md @@ -0,0 +1,25 @@ +# Clean Architecture - Folder Structure + +## Layering publisher/subscriber logic + +```mermaid +graph TD + App[src/] --> Web[infrastructure/web] + App --> Db[infrastructure/db] + App --> Core[core/] + Core --> UseCases[use-cases/] + Core --> Entities[entities/] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class App layout; + class Web component; + class Db component; + class Core layout; + class UseCases component; + class Entities component; +``` + +### Constraints +- Inner layers cannot import from outer layers. diff --git a/architectures/clean-architecture/implementation-guide.md b/architectures/clean-architecture/implementation-guide.md new file mode 100644 index 0000000..4ecac27 --- /dev/null +++ b/architectures/clean-architecture/implementation-guide.md @@ -0,0 +1,25 @@ +# Clean Architecture - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class UseCase { + +execute() + } + class Entity { + +validate() + } + class RepositoryInterface { + <> + +save() + } + UseCase --> Entity + UseCase --> RepositoryInterface +``` + +### Rules +- Dependency Inversion Principle must be strictly followed. +- Entities encapsulate the most general and high-level rules. diff --git a/architectures/clean-architecture/readme.md b/architectures/clean-architecture/readme.md new file mode 100644 index 0000000..ed05269 --- /dev/null +++ b/architectures/clean-architecture/readme.md @@ -0,0 +1,34 @@ +--- +description: Vibe coding guidelines and architectural constraints for Clean Architecture within the Architecture domain. +technology: Clean Architecture +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [architecture, system-design, clean-architecture, best-practices] +ai_role: Senior Architect +last_updated: 2026-03-22 +--- + +
+ # πŸ›οΈ Clean Architecture Production-Ready Best Practices +
+ +--- + +Π­Ρ‚ΠΎΡ‚ ΠΈΠ½ΠΆΠ΅Π½Π΅Ρ€Π½Ρ‹ΠΉ Π΄ΠΈΡ€Π΅ΠΊΡ‚ΠΈΠ² опрСдСляСт **Π»ΡƒΡ‡ΡˆΠΈΠ΅ ΠΏΡ€Π°ΠΊΡ‚ΠΈΠΊΠΈ (best practices)** для Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρ‹ Clean Architecture. Π”Π°Π½Π½Ρ‹ΠΉ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚ спроСктирован для обСспСчСния максимальной ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΠΎΡΡ‚ΠΈ, бСзопасности ΠΈ качСства ΠΊΠΎΠ΄Π° ΠΏΡ€ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ ΠΏΡ€ΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠΉ ΠΊΠΎΡ€ΠΏΠΎΡ€Π°Ρ‚ΠΈΠ²Π½ΠΎΠ³ΠΎ уровня. + +# Context & Scope +- **Primary Goal:** ΠŸΡ€Π΅Π΄ΠΎΡΡ‚Π°Π²ΠΈΡ‚ΡŒ строгиС Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Π½Ρ‹Π΅ ΠΏΡ€Π°Π²ΠΈΠ»Π° ΠΈ практичСскиС ΠΏΠ°Ρ‚Ρ‚Π΅Ρ€Π½Ρ‹ для создания ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΡ‹Ρ… систСм. +- **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 can only point inward. + +## 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 + +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. diff --git a/architectures/clean-architecture/trade-offs.md b/architectures/clean-architecture/trade-offs.md new file mode 100644 index 0000000..6ce6b4c --- /dev/null +++ b/architectures/clean-architecture/trade-offs.md @@ -0,0 +1,12 @@ +# Clean Architecture - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- High testability. +- Framework agnostic. +- Database agnostic. + +### Cons +- Increased boilerplate and indirection. +- Steep learning curve for beginners. diff --git a/architectures/cqrs/data-flow.md b/architectures/cqrs/data-flow.md new file mode 100644 index 0000000..dfb02dc --- /dev/null +++ b/architectures/cqrs/data-flow.md @@ -0,0 +1,27 @@ +# CQRS - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant Client + participant CommandBus + participant CommandHandler + participant WriteDB + participant EventBus + participant QueryHandler + participant ReadDB + + Client->>CommandBus: Send Command (Mutate) + CommandBus->>CommandHandler: Execute + CommandHandler->>WriteDB: Save state + CommandHandler->>EventBus: Publish Event + EventBus->>ReadDB: Update Read Model + Client->>QueryHandler: Request Data (Read) + QueryHandler->>ReadDB: Fetch + ReadDB-->>QueryHandler: Data + QueryHandler-->>Client: Response +``` + +### Constraints +- Strict separation between mutating operations (Commands) and reading operations (Queries). diff --git a/architectures/cqrs/folder-structure.md b/architectures/cqrs/folder-structure.md new file mode 100644 index 0000000..f9f00a7 --- /dev/null +++ b/architectures/cqrs/folder-structure.md @@ -0,0 +1,23 @@ +# CQRS - Folder Structure + +## Layering publisher/subscriber logic + +```mermaid +graph TD + App[src/] --> Commands[commands/] + App --> Queries[queries/] + Commands --> HandlersC[handlers/] + Queries --> HandlersQ[handlers/] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class App layout; + class Commands layout; + class Queries layout; + class HandlersC component; + class HandlersQ component; +``` + +### Constraints +- Commands and Queries do not share DTOs or models. diff --git a/architectures/cqrs/implementation-guide.md b/architectures/cqrs/implementation-guide.md new file mode 100644 index 0000000..d62d3a2 --- /dev/null +++ b/architectures/cqrs/implementation-guide.md @@ -0,0 +1,27 @@ +# CQRS - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class Command { + +String id + } + class Query { + +String filter + } + class CommandHandler { + +handle(Command) + } + class QueryHandler { + +handle(Query) + } + CommandHandler --> Command + QueryHandler --> Query +``` + +### Rules +- Never return business data from a Command (only ack or id). +- Queries must never mutate state. diff --git a/architectures/cqrs/readme.md b/architectures/cqrs/readme.md new file mode 100644 index 0000000..d92999b --- /dev/null +++ b/architectures/cqrs/readme.md @@ -0,0 +1,34 @@ +--- +description: Vibe coding guidelines and architectural constraints for CQRS (Command Query Responsibility Segregation) within the Architecture domain. +technology: CQRS (Command Query Responsibility Segregation) +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [architecture, system-design, cqrs, best-practices] +ai_role: Senior Architect +last_updated: 2026-03-22 +--- + +
+ # πŸ›οΈ CQRS (Command Query Responsibility Segregation) Production-Ready Best Practices +
+ +--- + +Π­Ρ‚ΠΎΡ‚ ΠΈΠ½ΠΆΠ΅Π½Π΅Ρ€Π½Ρ‹ΠΉ Π΄ΠΈΡ€Π΅ΠΊΡ‚ΠΈΠ² опрСдСляСт **Π»ΡƒΡ‡ΡˆΠΈΠ΅ ΠΏΡ€Π°ΠΊΡ‚ΠΈΠΊΠΈ (best practices)** для Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρ‹ CQRS (Command Query Responsibility Segregation). Π”Π°Π½Π½Ρ‹ΠΉ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚ спроСктирован для обСспСчСния максимальной ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΠΎΡΡ‚ΠΈ, бСзопасности ΠΈ качСства ΠΊΠΎΠ΄Π° ΠΏΡ€ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ ΠΏΡ€ΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠΉ ΠΊΠΎΡ€ΠΏΠΎΡ€Π°Ρ‚ΠΈΠ²Π½ΠΎΠ³ΠΎ уровня. + +# Context & Scope +- **Primary Goal:** ΠŸΡ€Π΅Π΄ΠΎΡΡ‚Π°Π²ΠΈΡ‚ΡŒ строгиС Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Π½Ρ‹Π΅ ΠΏΡ€Π°Π²ΠΈΠ»Π° ΠΈ практичСскиС ΠΏΠ°Ρ‚Ρ‚Π΅Ρ€Π½Ρ‹ для создания ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΡ‹Ρ… систСм. +- **Description:** A powerful pattern where Commands (actions that mutate system data) are entirely decoupled from Queries (actions that only read data). + +## 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 + +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. diff --git a/architectures/cqrs/trade-offs.md b/architectures/cqrs/trade-offs.md new file mode 100644 index 0000000..1292541 --- /dev/null +++ b/architectures/cqrs/trade-offs.md @@ -0,0 +1,11 @@ +# CQRS - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- Independent scaling of read and write workloads. +- Optimized data schemas for read vs write operations. + +### Cons +- Eventual consistency complexity. +- High architectural overhead for simple domains. diff --git a/architectures/domain-driven-design/data-flow.md b/architectures/domain-driven-design/data-flow.md new file mode 100644 index 0000000..1a455ad --- /dev/null +++ b/architectures/domain-driven-design/data-flow.md @@ -0,0 +1,22 @@ +# Domain-Driven Design - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant UI + participant ApplicationService + participant AggregateRoot + participant Repository + + UI->>ApplicationService: Use Case Request + ApplicationService->>Repository: Get Aggregate + Repository-->>ApplicationService: Aggregate + ApplicationService->>AggregateRoot: Execute Behavior + ApplicationService->>Repository: Save Aggregate + Repository-->>ApplicationService: Success + ApplicationService-->>UI: Response +``` + +### Constraints +- State mutation must be coordinated through an Aggregate Root. diff --git a/architectures/domain-driven-design/folder-structure.md b/architectures/domain-driven-design/folder-structure.md new file mode 100644 index 0000000..8a4e8ee --- /dev/null +++ b/architectures/domain-driven-design/folder-structure.md @@ -0,0 +1,22 @@ +# Domain-Driven Design - Folder Structure + +## Layering logic + +```mermaid +graph TD + Domain[domain/] --> Aggregates[aggregates/] + Domain --> Entities[entities/] + Domain --> ValueObjects[value-objects/] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class Domain layout; + class Aggregates component; + class Entities component; + class ValueObjects component; +``` + +### Constraints +- Value Objects must be immutable. +- Domain layer must not depend on infrastructure. diff --git a/architectures/domain-driven-design/implementation-guide.md b/architectures/domain-driven-design/implementation-guide.md new file mode 100644 index 0000000..b48ddbd --- /dev/null +++ b/architectures/domain-driven-design/implementation-guide.md @@ -0,0 +1,20 @@ +# Domain-Driven Design - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class AggregateRoot { + +List~Entity~ entities + +commitEvents() + } + class ValueObject { + +equals() + } + AggregateRoot "1" *-- "many" ValueObject +``` + +### Rules +- Ubiquitous language must be strictly used in code. diff --git a/architectures/domain-driven-design/readme.md b/architectures/domain-driven-design/readme.md new file mode 100644 index 0000000..230efbe --- /dev/null +++ b/architectures/domain-driven-design/readme.md @@ -0,0 +1,34 @@ +--- +description: Vibe coding guidelines and architectural constraints for Domain-Driven Design within the Architecture domain. +technology: Domain-Driven Design +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [architecture, system-design, domain-driven-design, best-practices] +ai_role: Senior Architect +last_updated: 2026-03-22 +--- + +
+ # πŸ›οΈ Domain-Driven Design Production-Ready Best Practices +
+ +--- + +Π­Ρ‚ΠΎΡ‚ ΠΈΠ½ΠΆΠ΅Π½Π΅Ρ€Π½Ρ‹ΠΉ Π΄ΠΈΡ€Π΅ΠΊΡ‚ΠΈΠ² опрСдСляСт **Π»ΡƒΡ‡ΡˆΠΈΠ΅ ΠΏΡ€Π°ΠΊΡ‚ΠΈΠΊΠΈ (best practices)** для Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρ‹ Domain-Driven Design. Π”Π°Π½Π½Ρ‹ΠΉ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚ спроСктирован для обСспСчСния максимальной ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΠΎΡΡ‚ΠΈ, бСзопасности ΠΈ качСства ΠΊΠΎΠ΄Π° ΠΏΡ€ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ ΠΏΡ€ΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠΉ ΠΊΠΎΡ€ΠΏΠΎΡ€Π°Ρ‚ΠΈΠ²Π½ΠΎΠ³ΠΎ уровня. + +# 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 +- πŸ“Š [**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 + +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. diff --git a/architectures/domain-driven-design/trade-offs.md b/architectures/domain-driven-design/trade-offs.md new file mode 100644 index 0000000..e787dd5 --- /dev/null +++ b/architectures/domain-driven-design/trade-offs.md @@ -0,0 +1,11 @@ +# Domain-Driven Design - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- Aligns code strictly with business realities. +- High focus on the core domain complexity. + +### Cons +- Extreme overhead for CRUD operations. +- Requires domain experts collaboration. diff --git a/architectures/feature-sliced-design/data-flow.md b/architectures/feature-sliced-design/data-flow.md new file mode 100644 index 0000000..ee18e85 --- /dev/null +++ b/architectures/feature-sliced-design/data-flow.md @@ -0,0 +1,28 @@ +# Feature-Sliced Design (FSD) - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant User + participant Page as Page (UI) + participant Widget as Widget + participant Feature as Feature (Action) + participant Entity as Entity (State) + participant Shared as Shared (API/Infra) + + User->>Page: Interactions (Click/Input) + Page->>Widget: Compose Features & Entities + Widget->>Feature: Trigger Action (e.g. Add to Cart) + Feature->>Entity: Update Domain State / Selectors + Feature->>Shared: API Request (if needed) + Shared-->>Feature: API Response + Feature-->>Widget: Propagate changes + Widget-->>Page: Re-render UI + Page-->>User: Visual Update +``` + +### Constraints +- Unidirectional flow: State changes must propagate from top to bottom. +- Features encapsulate business logic. +- Entities store domain state. diff --git a/architectures/feature-sliced-design/folder-structure.md b/architectures/feature-sliced-design/folder-structure.md new file mode 100644 index 0000000..2472d05 --- /dev/null +++ b/architectures/feature-sliced-design/folder-structure.md @@ -0,0 +1,30 @@ +# Feature-Sliced Design (FSD) - Folder Structure + +## Layering publisher/subscriber logic + +```mermaid +graph TD + App[app] --> Pages[pages] + Pages --> Widgets[widgets] + Widgets --> Features[features] + Features --> Entities[entities] + Entities --> Shared[shared] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class Shared component; + class Features component; + class Pages layout; + class App layout; + class Entities component; + class Widgets component; +``` + +### Constraints +- **app**: Global settings, styles, providers. +- **pages**: Composition of widgets and features. Route components. +- **widgets**: Composition layer. Combines features and entities into meaningful blocks. +- **features**: User scenarios, business value actions (e.g., SendMessage, AddToCart). +- **entities**: Business entities (e.g., User, Product, Order). +- **shared**: Reusable UI components, utilities, api setup. diff --git a/architectures/feature-sliced-design/implementation-guide.md b/architectures/feature-sliced-design/implementation-guide.md new file mode 100644 index 0000000..284c7d8 --- /dev/null +++ b/architectures/feature-sliced-design/implementation-guide.md @@ -0,0 +1,37 @@ +# Feature-Sliced Design (FSD) - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class User { + +String id + +String name + +String email + +updateProfile() + } + class Order { + +String id + +Float total + +String status + +process() + } + class Product { + +String id + +String title + +Float price + } + User "1" *-- "many" Order : places + Order "1" *-- "many" Product : contains +``` + +### Rules for implementation: +1. **Public API**: Every slice and segment must have an `index.ts` (Public API) to expose its contents. +2. **Cross-Slice Imports**: Cross-slice imports within the same layer are strictly prohibited. +3. **Global State**: Global state (like Redux or Zustand) should be split across entities and features, not centralized in one huge store. + +### Anti-patterns: +- **God Object**: Creating a single feature that handles too many responsibilities. +- **Bypassing Layers**: Importing `shared` directly into `app` without going through intermediate layers if applicable, though `shared` is accessible everywhere. More importantly, `entities` importing from `features` is a strict violation. diff --git a/architectures/feature-sliced-design/readme.md b/architectures/feature-sliced-design/readme.md index baaeb4a..56eac15 100644 --- a/architectures/feature-sliced-design/readme.md +++ b/architectures/feature-sliced-design/readme.md @@ -19,6 +19,13 @@ 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. + +## 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 ### ❌ Bad Practice diff --git a/architectures/feature-sliced-design/trade-offs.md b/architectures/feature-sliced-design/trade-offs.md new file mode 100644 index 0000000..a464a05 --- /dev/null +++ b/architectures/feature-sliced-design/trade-offs.md @@ -0,0 +1,18 @@ +# Feature-Sliced Design (FSD) - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- **High Cohesion & Low Coupling**: Modules are highly independent. +- **Scalability**: New features can be added without affecting existing ones. +- **Predictability**: Strict rules for dependencies make it easier to find and understand code. +- **Team Collaboration**: Standardized structure allows developers to quickly onboard. + +### Cons +- **Steep Learning Curve**: Strict rules require discipline and understanding from the team. +- **Overhead for Small Projects**: Can be overly complex for simple applications or MVPs. +- **Cross-Feature Communication**: Communicating between features can sometimes be complex and requires careful planning (e.g., using Event Bus or lifting state). + +### Boundaries +- A layer can only import from layers strictly below it. +- Slices within the same layer cannot import from each other directly (use public API). diff --git a/architectures/microservices/data-flow.md b/architectures/microservices/data-flow.md new file mode 100644 index 0000000..05206f2 --- /dev/null +++ b/architectures/microservices/data-flow.md @@ -0,0 +1,21 @@ +# Microservices - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant Client + participant API_Gateway + participant Auth_Service + participant Product_Service + + Client->>API_Gateway: Request + API_Gateway->>Auth_Service: Validate Token + Auth_Service-->>API_Gateway: Valid + API_Gateway->>Product_Service: Forward Request + Product_Service-->>API_Gateway: Response + API_Gateway-->>Client: Payload +``` + +### Constraints +- Services must be independently deployable. diff --git a/architectures/microservices/folder-structure.md b/architectures/microservices/folder-structure.md new file mode 100644 index 0000000..4a82a23 --- /dev/null +++ b/architectures/microservices/folder-structure.md @@ -0,0 +1,23 @@ +# Microservices - Folder Structure + +## Layering logic + +```mermaid +graph TD + System[Platform/] --> Svc1[auth-service/] + System --> Svc2[order-service/] + Svc1 --> Svc1DB[(Auth DB)] + Svc2 --> Svc2DB[(Order DB)] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class System layout; + class Svc1 component; + class Svc2 component; + class Svc1DB component; + class Svc2DB component; +``` + +### Constraints +- Each service owns its database. diff --git a/architectures/microservices/implementation-guide.md b/architectures/microservices/implementation-guide.md new file mode 100644 index 0000000..421c6ef --- /dev/null +++ b/architectures/microservices/implementation-guide.md @@ -0,0 +1,19 @@ +# Microservices - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class Gateway { + +route() + } + class Service { + +process() + } + Gateway --> Service : RPC/HTTP +``` + +### Rules +- Avoid synchronous cascading calls between services. diff --git a/architectures/microservices/readme.md b/architectures/microservices/readme.md new file mode 100644 index 0000000..287ba2d --- /dev/null +++ b/architectures/microservices/readme.md @@ -0,0 +1,34 @@ +--- +description: Vibe coding guidelines and architectural constraints for Microservices within the Architecture domain. +technology: Microservices +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [architecture, system-design, microservices, best-practices] +ai_role: Senior Architect +last_updated: 2026-03-22 +--- + +
+ # πŸ›οΈ Microservices Production-Ready Best Practices +
+ +--- + +Π­Ρ‚ΠΎΡ‚ ΠΈΠ½ΠΆΠ΅Π½Π΅Ρ€Π½Ρ‹ΠΉ Π΄ΠΈΡ€Π΅ΠΊΡ‚ΠΈΠ² опрСдСляСт **Π»ΡƒΡ‡ΡˆΠΈΠ΅ ΠΏΡ€Π°ΠΊΡ‚ΠΈΠΊΠΈ (best practices)** для Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρ‹ Microservices. Π”Π°Π½Π½Ρ‹ΠΉ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚ спроСктирован для обСспСчСния максимальной ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΠΎΡΡ‚ΠΈ, бСзопасности ΠΈ качСства ΠΊΠΎΠ΄Π° ΠΏΡ€ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ ΠΏΡ€ΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠΉ ΠΊΠΎΡ€ΠΏΠΎΡ€Π°Ρ‚ΠΈΠ²Π½ΠΎΠ³ΠΎ уровня. + +# Context & Scope +- **Primary Goal:** ΠŸΡ€Π΅Π΄ΠΎΡΡ‚Π°Π²ΠΈΡ‚ΡŒ строгиС Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Π½Ρ‹Π΅ ΠΏΡ€Π°Π²ΠΈΠ»Π° ΠΈ практичСскиС ΠΏΠ°Ρ‚Ρ‚Π΅Ρ€Π½Ρ‹ для создания ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΡ‹Ρ… систСм. +- **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 +- πŸ“Š [**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 + +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. diff --git a/architectures/microservices/trade-offs.md b/architectures/microservices/trade-offs.md new file mode 100644 index 0000000..dbc737d --- /dev/null +++ b/architectures/microservices/trade-offs.md @@ -0,0 +1,11 @@ +# Microservices - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- Independent scaling. +- Technological freedom per service. + +### Cons +- Distributed system complexity. +- Difficult cross-service transactions. diff --git a/architectures/model-view-controller/data-flow.md b/architectures/model-view-controller/data-flow.md new file mode 100644 index 0000000..0a4604c --- /dev/null +++ b/architectures/model-view-controller/data-flow.md @@ -0,0 +1,27 @@ +# Model-View-Controller (MVC) - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant User + participant Router as Router + participant Controller as Controller + participant Service as Service + participant Database as Database + participant View as View + + User->>Router: HTTP Request (e.g. GET /users) + Router->>Controller: Route to handler + Controller->>Service: Delegate business logic + Service->>Database: Query data + Database-->>Service: Return data + Service-->>Controller: Return processed DTO + Controller->>View: Render with DTO + View-->>User: HTTP Response (HTML/JSON) +``` + +### Constraints +- Unidirectional request flow: User -> Controller -> Service -> DB -> View -> User. +- Controller orchestrates, it does not contain business logic. +- View is pure presentation and rendering. diff --git a/architectures/model-view-controller/folder-structure.md b/architectures/model-view-controller/folder-structure.md new file mode 100644 index 0000000..69ad105 --- /dev/null +++ b/architectures/model-view-controller/folder-structure.md @@ -0,0 +1,31 @@ +# Model-View-Controller (MVC) - Folder Structure + +## Layering publisher/subscriber logic + +```mermaid +graph TD + App[src/] --> Routes[routes/] + Routes --> Controllers[controllers/] + Controllers --> Services[services/] + Services --> Models[models/] + Models --> Config[config/] + Controllers --> Views[views/] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class Models component; + class Services component; + class Controllers component; + class Routes layout; + class Views layout; + class Config component; + class App layout; +``` + +### Constraints +- **controllers**: Orchestrate requests and responses. Thin layer. +- **services**: Heavy lifting, core business rules, and use case implementations. +- **models**: Data persistence definitions, ORM mapping. +- **views**: Presentation layer (e.g. Handlebars, EJS, React components). +- **routes**: API endpoints definition, mapping URLs to controllers. diff --git a/architectures/model-view-controller/implementation-guide.md b/architectures/model-view-controller/implementation-guide.md new file mode 100644 index 0000000..0a1229b --- /dev/null +++ b/architectures/model-view-controller/implementation-guide.md @@ -0,0 +1,34 @@ +# Model-View-Controller (MVC) - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class Controller { + +handleRequest() + } + class Service { + +executeBusinessLogic() + } + class Model { + +saveToDatabase() + } + class View { + +render() + } + Controller --> Service : delegates + Controller --> View : chooses + Service --> Model : manipulates +``` + +### Rules for implementation: +1. **Thin Controllers**: Move all business logic into Service classes. +2. **DTOs**: Pass Data Transfer Objects between layers to avoid leaking DB schemas. +3. **Dependency Injection**: Use DI to pass services into controllers for better testability. + +### Anti-patterns: +- **Fat Controllers**: Containing raw SQL, business logic, or file system access. +- **Logic in Views**: Conditional statements that reflect business rules in the UI layer. +- **Database Logic in Controllers**: Controllers directly calling `ORM.find()` or similar. diff --git a/architectures/model-view-controller/readme.md b/architectures/model-view-controller/readme.md index ba9df4b..268df59 100644 --- a/architectures/model-view-controller/readme.md +++ b/architectures/model-view-controller/readme.md @@ -58,6 +58,13 @@ graph TD --- + +## 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) ### ❌ Bad Practice diff --git a/architectures/model-view-controller/trade-offs.md b/architectures/model-view-controller/trade-offs.md new file mode 100644 index 0000000..7e069af --- /dev/null +++ b/architectures/model-view-controller/trade-offs.md @@ -0,0 +1,19 @@ +# Model-View-Controller (MVC) - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- **Familiarity**: Easy to understand, widely adopted pattern. +- **Separation of Concerns**: Clear distinction between data, UI, and control logic. +- **Rapid Development**: Excellent for starting MVP applications. +- **Framework Support**: High support across many frameworks (Spring, Express, Rails, Django). + +### Cons +- **Scalability**: For very large apps, "fat controllers" and "fat models" become common. +- **Coupling**: Often strong coupling between view and controller. +- **Complexity over time**: Harder to maintain when domains grow too complex, often necessitating a move to DDD or Clean Architecture. + +### Boundaries +- Controllers must never execute direct database queries. +- Views must not contain business logic or query the DB. +- Models should not format data for views. diff --git a/architectures/monolithic-architecture/data-flow.md b/architectures/monolithic-architecture/data-flow.md new file mode 100644 index 0000000..a50f81a --- /dev/null +++ b/architectures/monolithic-architecture/data-flow.md @@ -0,0 +1,20 @@ +# Monolithic Architecture - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant Client + participant LoadBalancer + participant Monolith + participant Database + + Client->>LoadBalancer: Request + LoadBalancer->>Monolith: Route + Monolith->>Database: Query + Database-->>Monolith: Data + Monolith-->>Client: Response +``` + +### Constraints +- All bounded contexts run in the same process. diff --git a/architectures/monolithic-architecture/folder-structure.md b/architectures/monolithic-architecture/folder-structure.md new file mode 100644 index 0000000..1d2b8ae --- /dev/null +++ b/architectures/monolithic-architecture/folder-structure.md @@ -0,0 +1,21 @@ +# Monolithic Architecture - Folder Structure + +## Layering logic + +```mermaid +graph TD + App[src/] --> Modules[modules/] + Modules --> Auth[auth/] + Modules --> Billing[billing/] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class App layout; + class Modules layout; + class Auth component; + class Billing component; +``` + +### Constraints +- Strict modular boundaries to prevent spaghetti code. diff --git a/architectures/monolithic-architecture/implementation-guide.md b/architectures/monolithic-architecture/implementation-guide.md new file mode 100644 index 0000000..7b30519 --- /dev/null +++ b/architectures/monolithic-architecture/implementation-guide.md @@ -0,0 +1,19 @@ +# Monolithic Architecture - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class Module { + +API + } + class Database { + +Schema + } + Module --> Database +``` + +### Rules +- Adopt Modular Monolith principles over time. diff --git a/architectures/monolithic-architecture/readme.md b/architectures/monolithic-architecture/readme.md new file mode 100644 index 0000000..ae3524d --- /dev/null +++ b/architectures/monolithic-architecture/readme.md @@ -0,0 +1,34 @@ +--- +description: Vibe coding guidelines and architectural constraints for Monolithic Architecture within the Architecture domain. +technology: Monolithic Architecture +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [architecture, system-design, monolithic-architecture, best-practices] +ai_role: Senior Architect +last_updated: 2026-03-22 +--- + +
+ # πŸ›οΈ Monolithic Architecture Production-Ready Best Practices +
+ +--- + +Π­Ρ‚ΠΎΡ‚ ΠΈΠ½ΠΆΠ΅Π½Π΅Ρ€Π½Ρ‹ΠΉ Π΄ΠΈΡ€Π΅ΠΊΡ‚ΠΈΠ² опрСдСляСт **Π»ΡƒΡ‡ΡˆΠΈΠ΅ ΠΏΡ€Π°ΠΊΡ‚ΠΈΠΊΠΈ (best practices)** для Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρ‹ Monolithic Architecture. Π”Π°Π½Π½Ρ‹ΠΉ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚ спроСктирован для обСспСчСния максимальной ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΠΎΡΡ‚ΠΈ, бСзопасности ΠΈ качСства ΠΊΠΎΠ΄Π° ΠΏΡ€ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ ΠΏΡ€ΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠΉ ΠΊΠΎΡ€ΠΏΠΎΡ€Π°Ρ‚ΠΈΠ²Π½ΠΎΠ³ΠΎ уровня. + +# 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 +- πŸ“Š [**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 + +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. diff --git a/architectures/monolithic-architecture/trade-offs.md b/architectures/monolithic-architecture/trade-offs.md new file mode 100644 index 0000000..c76309e --- /dev/null +++ b/architectures/monolithic-architecture/trade-offs.md @@ -0,0 +1,11 @@ +# Monolithic Architecture - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- Easy to develop, test, and deploy. +- Strong transactional guarantees (ACID). + +### Cons +- Scales as a whole, not by component. +- Large codebase can slow down IDEs and startup times. diff --git a/architectures/readme.md b/architectures/readme.md index 390f847..44be9f3 100644 --- a/architectures/readme.md +++ b/architectures/readme.md @@ -101,6 +101,7 @@ src/ [![Clean Arch](https://img.shields.io/badge/Clean_Architecture-black?style=flat-square)](#) **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 can only point inward (towards core business entities). +**πŸ“– Map of Patterns:** [Go to Clean Architecture Guidelines](./clean-architecture/readme.md) **Architecture Diagram & Folder Tree:** ```mermaid @@ -180,6 +181,7 @@ src/ 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. +**πŸ“– Map of Patterns:** [Go to Microservices Guidelines](./microservices/readme.md) **Architecture Diagram & Folder Tree:** ```mermaid @@ -267,6 +269,7 @@ src/ [![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`. +**πŸ“– Map of Patterns:** [Go to DDD Guidelines](./domain-driven-design/readme.md) **Architecture Diagram & Folder Tree:** ```mermaid @@ -308,6 +311,7 @@ src/ 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. +**πŸ“– Map of Patterns:** [Go to Event-Driven Architecture Guidelines](./event-driven-architecture/readme.md) **πŸ“– Map of Patterns:** [Go to EDA Guidelines](./event-driven-architecture/readme.md) **Architecture Diagram & Folder Tree:** @@ -347,6 +351,7 @@ src/ 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. +**πŸ“– Map of Patterns:** [Go to Serverless Guidelines](./serverless/readme.md) **Architecture Diagram & Folder Tree:** ```mermaid @@ -385,6 +390,7 @@ project-functions/ [![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. +**πŸ“– Map of Patterns:** [Go to Monolithic Architecture Guidelines](./monolithic-architecture/readme.md) **Architecture Diagram & Folder Tree:** ```mermaid @@ -423,6 +429,7 @@ monolith-app/ [![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. +**πŸ“– Map of Patterns:** [Go to CQRS Guidelines](./cqrs/readme.md) **Architecture Diagram & Folder Tree:** ```mermaid diff --git a/architectures/serverless/data-flow.md b/architectures/serverless/data-flow.md new file mode 100644 index 0000000..95cfe53 --- /dev/null +++ b/architectures/serverless/data-flow.md @@ -0,0 +1,21 @@ +# Serverless - Data Flow + +## Request and Event Lifecycle + +```mermaid +sequenceDiagram + participant Client + participant API_Gateway + participant LambdaFunction + participant DynamoDB + + Client->>API_Gateway: HTTP Request + API_Gateway->>LambdaFunction: Trigger Execution + LambdaFunction->>DynamoDB: Persist Data + DynamoDB-->>LambdaFunction: Ack + LambdaFunction-->>API_Gateway: Return + API_Gateway-->>Client: HTTP Response +``` + +### Constraints +- Functions must be stateless. diff --git a/architectures/serverless/folder-structure.md b/architectures/serverless/folder-structure.md new file mode 100644 index 0000000..a6dd8cc --- /dev/null +++ b/architectures/serverless/folder-structure.md @@ -0,0 +1,23 @@ +# Serverless - Folder Structure + +## Layering logic + +```mermaid +graph TD + App[functions/] --> F1[getUser/] + App --> F2[createUser/] + F1 --> index[index.js] + F2 --> index2[index.js] + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000; + + class App layout; + class F1 layout; + class F2 layout; + class index component; + class index2 component; +``` + +### Constraints +- Functions are self-contained. diff --git a/architectures/serverless/implementation-guide.md b/architectures/serverless/implementation-guide.md new file mode 100644 index 0000000..2642fbb --- /dev/null +++ b/architectures/serverless/implementation-guide.md @@ -0,0 +1,19 @@ +# Serverless - Implementation Guide + +## Code patterns and Anti-patterns + +### Entity Relationships + +```mermaid +classDiagram + class Function { + +handler(event, context) + } + class Resource { + +arn + } + Function --> Resource +``` + +### Rules +- Minimize dependencies to reduce cold start times. diff --git a/architectures/serverless/readme.md b/architectures/serverless/readme.md new file mode 100644 index 0000000..e3926f3 --- /dev/null +++ b/architectures/serverless/readme.md @@ -0,0 +1,34 @@ +--- +description: Vibe coding guidelines and architectural constraints for Serverless within the Architecture domain. +technology: Serverless +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [architecture, system-design, serverless, best-practices] +ai_role: Senior Architect +last_updated: 2026-03-22 +--- + +
+ # πŸ›οΈ Serverless Production-Ready Best Practices +
+ +--- + +Π­Ρ‚ΠΎΡ‚ ΠΈΠ½ΠΆΠ΅Π½Π΅Ρ€Π½Ρ‹ΠΉ Π΄ΠΈΡ€Π΅ΠΊΡ‚ΠΈΠ² опрСдСляСт **Π»ΡƒΡ‡ΡˆΠΈΠ΅ ΠΏΡ€Π°ΠΊΡ‚ΠΈΠΊΠΈ (best practices)** для Π°Ρ€Ρ…ΠΈΡ‚Π΅ΠΊΡ‚ΡƒΡ€Ρ‹ Serverless. Π”Π°Π½Π½Ρ‹ΠΉ Π΄ΠΎΠΊΡƒΠΌΠ΅Π½Ρ‚ спроСктирован для обСспСчСния максимальной ΠΌΠ°ΡΡˆΡ‚Π°Π±ΠΈΡ€ΡƒΠ΅ΠΌΠΎΡΡ‚ΠΈ, бСзопасности ΠΈ качСства ΠΊΠΎΠ΄Π° ΠΏΡ€ΠΈ Ρ€Π°Π·Ρ€Π°Π±ΠΎΡ‚ΠΊΠ΅ ΠΏΡ€ΠΈΠ»ΠΎΠΆΠ΅Π½ΠΈΠΉ ΠΊΠΎΡ€ΠΏΠΎΡ€Π°Ρ‚ΠΈΠ²Π½ΠΎΠ³ΠΎ уровня. + +# 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 +- πŸ“Š [**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 + +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. diff --git a/architectures/serverless/trade-offs.md b/architectures/serverless/trade-offs.md new file mode 100644 index 0000000..50fa17c --- /dev/null +++ b/architectures/serverless/trade-offs.md @@ -0,0 +1,11 @@ +# Serverless - Trade-offs + +## Pros, Cons, and System Constraints + +### Pros +- Zero server management. +- Scales to zero (cost effective). + +### Cons +- Cold starts. +- Vendor lock-in (AWS, GCP, Azure).