From 8c65ffee987dd55fc7685577dc0f55361c780357 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 19 May 2026 17:30:55 +0000 Subject: [PATCH] docs(arch): autonomous evolution of architecture blueprints Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com> --- architectures/agentic-architecture/readme.md | 9 ++++++++ architectures/backend-for-frontend/readme.md | 4 +++- architectures/feature-sliced-design/readme.md | 23 ++++++++++++++++++- .../hexagonal-architecture/readme.md | 9 ++++++++ .../microkernel-architecture/readme.md | 9 ++++++++ architectures/microservices/readme.md | 4 +++- architectures/model-view-controller/readme.md | 11 ++++++++- 7 files changed, 65 insertions(+), 4 deletions(-) diff --git a/architectures/agentic-architecture/readme.md b/architectures/agentic-architecture/readme.md index 3c0fef7..e43dd25 100644 --- a/architectures/agentic-architecture/readme.md +++ b/architectures/agentic-architecture/readme.md @@ -22,6 +22,13 @@ last_updated: 2026-04-17 --- + +## 🧱 Core Principles + +1. **Isolation & Testability:** Specialized agents can be tested and tuned in isolation from the orchestrator. +2. **Strict Boundaries:** Enforce rigid responsibilities between planners, coders, and reviewers. +3. **Decoupling:** Decouple context gathering from action execution to optimize token usage. + ## πŸ—ΊοΈ Map of Patterns (Agentic Modules) This architecture defines the operational boundaries for multi-agent workflows, specifically optimizing for context windows, token efficiency, and deterministic output. @@ -31,6 +38,8 @@ This architecture defines the operational boundaries for multi-agent workflows, - βš–οΈ **Trade-offs:** Latency vs. Reasoning depth. - πŸ› οΈ **Implementation Guide:** Rules for defining strict agent personas and constraints. +## πŸ“ Architecture Diagram + ```mermaid graph TD User[User Request] --> Orchestrator[Orchestrator Agent] diff --git a/architectures/backend-for-frontend/readme.md b/architectures/backend-for-frontend/readme.md index 490df6f..54db198 100644 --- a/architectures/backend-for-frontend/readme.md +++ b/architectures/backend-for-frontend/readme.md @@ -16,7 +16,7 @@ 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. @@ -38,6 +38,8 @@ This engineering directive defines the **best practices** for the Backend-For-Fr | **Complexity** | Multiple BFFs to manage | Single point of failure/bottleneck | +## πŸ“ Architecture Diagram + ```mermaid graph TD Web[Web Client] --> BFF_Web[BFF Web] diff --git a/architectures/feature-sliced-design/readme.md b/architectures/feature-sliced-design/readme.md index bf6870f..b02111f 100644 --- a/architectures/feature-sliced-design/readme.md +++ b/architectures/feature-sliced-design/readme.md @@ -13,12 +13,33 @@ last_updated: 2026-03-22 FSD Logo # 🍰 Feature-Sliced Design (FSD) + + --- +## 🎯 Context & Scope +- **Primary Goal:** Establish definitive rules and best practices for modular, scalable frontend development. +- **Target Tooling:** AI Agents and Human Developers. +- **Tech Stack Version:** Agnostic (React, Vue, Angular) + +--- 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:** Layer-to-layer execution paths and slice interactions. +- πŸ“ **Folder Structure:** Strict vertical (slices) and horizontal (layers) isolation. +- βš–οΈ **Trade-offs:** Initial overhead vs. long-term maintainability. +- πŸ› οΈ **Implementation Guide:** Rules for cross-imports and boundaries. + +## 🧱 Core Principles + +1. **Isolation & Testability:** Slices are completely isolated, making them highly testable and refactorable. +2. **Strict Boundaries:** Enforce strict cross-import boundaries (lower layers cannot import from higher layers). +3. **Decoupling:** Decouple business logic into cohesive modules rather than scattering it across technical layers. + ### Structural Comparison: Feature-Sliced Design vs Clean Architecture | Feature | Feature-Sliced Design (FSD) | Clean Architecture | @@ -28,7 +49,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 diff --git a/architectures/hexagonal-architecture/readme.md b/architectures/hexagonal-architecture/readme.md index 236bbe3..48b0492 100644 --- a/architectures/hexagonal-architecture/readme.md +++ b/architectures/hexagonal-architecture/readme.md @@ -20,6 +20,13 @@ last_updated: 2026-03-22 **Ports and Adapters for scalable, testable code.** --- + +## 🧱 Core Principles + +1. **Isolation & Testability:** The Domain is strictly isolated from infrastructure, allowing unit testing via Ports. +2. **Strict Boundaries:** Enforce rigid boundaries using Ports and Adapters to separate business logic from technical details. +3. **Decoupling:** Decouple the Core logic from databases, external APIs, and UIs. + ## πŸ—ΊοΈ Map of Patterns (Hexagonal Modules) This pattern documentation has been decomposed into specialized modules for zero-approval AI parsing and human comprehension. @@ -29,6 +36,8 @@ This pattern documentation has been decomposed into specialized modules for zero - βš–οΈ **[Trade-offs](./trade-offs.md):** Pros, cons, and architectural constraints. - πŸ› οΈ **[Implementation Guide](./implementation-guide.md):** Step-by-step rules and code constraints for Vibe Coding. +## πŸ“ Architecture Diagram + ```mermaid flowchart TD A[External System/User] -->|Calls Port| B(Adapter) diff --git a/architectures/microkernel-architecture/readme.md b/architectures/microkernel-architecture/readme.md index 20fbc2e..671399a 100644 --- a/architectures/microkernel-architecture/readme.md +++ b/architectures/microkernel-architecture/readme.md @@ -24,6 +24,13 @@ last_updated: 2026-04-18 --- + +## 🧱 Core Principles + +1. **Isolation & Testability:** Plugins can be tested in complete isolation from the core. +2. **Strict Boundaries:** Enforce rigid structural barriers between the core microkernel and plugins. +3. **Decoupling:** Decouple volatile domain logic from the stable core application logic. + ## πŸ—ΊοΈ Map of Patterns (Microkernel Modules) This architecture defines strict boundaries between a minimal core system and extended functionalities implemented as standalone plugins. It guarantees O(1) impact on the core when adding or modifying auxiliary features. @@ -33,6 +40,8 @@ This architecture defines strict boundaries between a minimal core system and ex - βš–οΈ **Trade-offs:** Extensibility vs. Contract Management complexity. - πŸ› οΈ **Implementation Guide:** Rules for defining strict interface boundaries and registry mechanisms. +## πŸ“ Architecture Diagram + ```mermaid graph TD Core[Core System / Microkernel] --> Registry[Plugin Registry] diff --git a/architectures/microservices/readme.md b/architectures/microservices/readme.md index f7cad4d..7f5a994 100644 --- a/architectures/microservices/readme.md +++ b/architectures/microservices/readme.md @@ -15,7 +15,7 @@ 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 @@ -39,6 +39,8 @@ This engineering directive defines the **best practices** for the Microservices 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 + ```mermaid graph LR Isolation[Isolation & Testability] --- Boundaries[Strict Boundaries] diff --git a/architectures/model-view-controller/readme.md b/architectures/model-view-controller/readme.md index 878e662..fe62cbf 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.). @@ -24,6 +24,8 @@ This engineering directive defines the **best practices** for the MVC architectu > **Architectural Contract:** The Controller receives the HTTP request and routes commands, Services (or Domain Model) contain the business logic, and the View is strictly responsible for rendering abstract Data Transfer Objects (DTOs). ## Architecture Flow (Mental Model) +## πŸ“ Architecture Diagram + ```mermaid graph TD User([User Request]) --> Router[Router] @@ -59,6 +61,13 @@ graph TD - πŸ“ [**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:** Views and Models are isolated from each other via Controllers. +2. **Strict Boundaries:** Enforce rigid structural boundaries between UI, logic, and data. +3. **Decoupling:** Decouple the UI from business logic to enable independent development. + ## 1. Fat Controllers (God Object Controller) ### ❌ Bad Practice