diff --git a/architectures/layered-architecture/readme.md b/architectures/layered-architecture/readme.md new file mode 100644 index 0000000..669b309 --- /dev/null +++ b/architectures/layered-architecture/readme.md @@ -0,0 +1,125 @@ +--- +technology: Layered Architecture (N-Tier) +domain: Architecture +level: Senior/Architect +version: Agnostic +tags: [architecture, system-design, layered-architecture, n-tier, best-practices] +ai_role: Senior Architect +last_updated: 2026-05-14 +--- + +
+ # πŸ›οΈ Layered Architecture (N-Tier) Production-Ready Best Practices +
+ +--- + +This engineering directive defines the **best practices** for Layered Architecture (also known as N-Tier Architecture). This document is designed to ensure maximum scalability, maintainability, and code quality by establishing strict hierarchical layer boundaries. + +# Context & Scope +- **Primary Goal:** Document and strictly enforce best practices for Layered Architecture to guarantee proper separation of concerns and deterministic system behavior. +- **Target Tooling:** AI Agents and Human Developers. +- **Tech Stack Version:** Agnostic + +
+ Layered Architecture Logo + + **Deterministic hierarchical blueprints for structured applications.** +
+ +--- +## πŸ—ΊοΈ Map of Patterns (Layered Modules) + +This architecture defines strict hierarchical boundaries separating different aspects of the system. Data strictly flows downward from one layer to the next adjacent layer. + +- 🌊 **Data Flow:** Presentation β†’ Business β†’ Persistence β†’ Database. +- πŸ“ **Folder Structure:** Rigid separation of UI, Services, and Repositories. +- βš–οΈ **Trade-offs:** Simplicity vs. Boilerplate code. +- πŸ› οΈ **Implementation Guide:** Rules for defining strict closed layers. + +```mermaid +graph TD + Presentation[Presentation Layer] --> Business[Business Logic Layer] + Business --> Persistence[Persistence / Data Access Layer] + Persistence --> Database[(Database)] + + %% Added Design Token Styles for Mermaid Diagrams + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + + class Presentation component; + class Business component; + class Persistence component; + class Database default; +``` + +## πŸš€ The Core Philosophy + +Layered Architecture establishes a hierarchical flow of dependencies where components in a specific layer can only interact with components in the same layer or the layer immediately below it. This is known as a **closed layer** architecture. + +> [!IMPORTANT] +> **AI Constraint:** Agents MUST NOT bypass layers. The Presentation layer MUST NOT communicate directly with the Persistence layer. All communication MUST pass sequentially through the intermediary Business layer to ensure deterministic enforcement of business rules. + +--- + +## 1. Bypassing Intermediary Layers (Layer Leaks) + +### ❌ Bad Practice +```typescript +class UserController { + // Presentation layer directly importing from Persistence layer + constructor(private readonly userRepository: UserRepository) {} + + async getUser(req: Request, res: Response) { + // Skipping Business Layer logic + const user = await this.userRepository.findById(req.params.id); + return res.status(200).json(user); + } +} +``` + +### ⚠️ Problem +When higher layers bypass intermediary layers to communicate directly with lower layers, the architecture becomes "open" and leaky. This circumvents critical business rules, authorization checks, and validation logic that reside in the bypassed layer. It leads to duplicate logic, fragile tight coupling, and massive security risks. + +### βœ… Best Practice +```typescript +// 1. Presentation Layer +class UserController { + // Strictly depends on the adjacent Business Layer + constructor(private readonly userService: UserService) {} + + async getUser(req: Request, res: Response) { + const user = await this.userService.getUserProfile(req.params.id); + return res.status(200).json(user); + } +} + +// 2. Business Layer +class UserService { + // Enforces business rules before calling Persistence + constructor(private readonly userRepository: UserRepository) {} + + async getUserProfile(id: string) { + if (!isValidId(id)) throw new Error("Invalid ID"); + + const user = await this.userRepository.findById(id); + if (!user) throw new Error("User not found"); + + // Business rule application + user.lastAccess = new Date(); + await this.userRepository.save(user); + + return user; + } +} + +// 3. Persistence Layer +class UserRepository { + async findById(id: string) { + return db.query(`SELECT * FROM users WHERE id = ?`, [id]); + } +} +``` + +### πŸš€ Solution +Strictly enforce **closed layers**. Every request must travel through each layer sequentially. The `Presentation` layer must solely translate incoming requests and pass them to the `Business` layer. The `Business` layer applies domain rules and delegates data operations to the `Persistence` layer. This guarantees determinism, proper isolation of concerns, and O(1) impact when refactoring an individual layer's internal implementation. diff --git a/architectures/readme.md b/architectures/readme.md index 266a53a..abda004 100644 --- a/architectures/readme.md +++ b/architectures/readme.md @@ -58,8 +58,9 @@ Don't know where to start? Here are a few golden rules: - [Space-Based Architecture](./space-based-architecture/readme.md) - [Serverless](./serverless/readme.md) - [Agentic Architecture (AI Agent Orchestration)](./agentic-architecture/readme.md) +- [Layered Architecture (N-Tier)](./layered-architecture/readme.md) -## πŸ† Top 15 Best Architectural Approaches +## πŸ† Top 17 Best Architectural Approaches 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. --- @@ -719,3 +720,39 @@ src/ - **Frameworks:** Eclipse, VS Code, Webpack, Babel. - **Languages:** TypeScript, Java, Python. - **Patterns / Principles:** Open/Closed Principle, Dependency Inversion, Registry Pattern. +--- + +### 17. Layered Architecture (N-Tier) +[![Layered Architecture](https://img.shields.io/badge/Architecture-Layered-blue?style=flat-square)](#) + +**Description:** An architecture that organizes a system into strict hierarchical layers. Data and control must flow sequentially from top to bottom (e.g., Presentation β†’ Business Logic β†’ Persistence β†’ Database). Bypassing layers is strictly prohibited to ensure maximum separation of concerns. +**πŸ“– Map of Patterns:** [Go to Layered Architecture Guidelines](./layered-architecture/readme.md) + +**Architecture Diagram & Folder Tree:** +```mermaid +graph TD + Presentation[Presentation Layer] --> Business[Business Logic Layer] + Business --> Persistence[Persistence / Data Access Layer] + Persistence --> Database[(Database)] + + %% Added Design Token Styles for Mermaid Diagrams + classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000; + classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000; + + class Presentation component; + class Business component; + class Persistence component; + class Database default; +``` + +```text +src/ +β”œβ”€β”€ πŸ“ presentation/ # Controllers, Routes, and View models +β”œβ”€β”€ πŸ“ business/ # Core business logic and rules +└── πŸ“ persistence/ # Repositories and Data Access Objects (DAOs) +``` + +**Best Compatibility:** +- **Frameworks:** Spring Boot, ASP.NET Core, Express.js. +- **Languages:** Java, C#, TypeScript. +- **Patterns / Principles:** Separation of Concerns, Closed Layers.