From b278c4d9505723d943e540db259fe6d3ad8cd42f Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
<161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 26 Mar 2026 17:29:48 +0000
Subject: [PATCH] feat(arch): initialize specialized documentation for
hexagonal-architecture and cross-links
Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com>
---
.../hexagonal-architecture/data-flow.md | 54 ++++++
.../folder-structure.md | 77 ++++++++
.../implementation-guide.md | 170 ++++++++++++++++++
.../hexagonal-architecture/readme.md | 41 +++++
.../hexagonal-architecture/trade-offs.md | 39 ++++
architectures/readme.md | 3 +
6 files changed, 384 insertions(+)
create mode 100644 architectures/hexagonal-architecture/data-flow.md
create mode 100644 architectures/hexagonal-architecture/folder-structure.md
create mode 100644 architectures/hexagonal-architecture/implementation-guide.md
create mode 100644 architectures/hexagonal-architecture/readme.md
create mode 100644 architectures/hexagonal-architecture/trade-offs.md
diff --git a/architectures/hexagonal-architecture/data-flow.md b/architectures/hexagonal-architecture/data-flow.md
new file mode 100644
index 0000000..a1d10d1
--- /dev/null
+++ b/architectures/hexagonal-architecture/data-flow.md
@@ -0,0 +1,54 @@
+---
+description: Hexagonal Architecture Data Flow rules for AI agents and developers. Understanding execution sequences across Ports and Adapters.
+technology: Hexagonal Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [best-practices, data-flow, hexagonal-architecture, ports-and-adapters]
+ai_role: Senior Software Architect
+last_updated: 2026-03-22
+---
+
+# π Hexagonal Architecture Data Flow Best Practices
+
+
+ **Execution paths and communication between layers.**
+
+
+---
+
+## π The Sequence of Execution
+
+In Hexagonal Architecture, a request from the outside world must pierce through the layers strictly via defined Interfaces (Ports).
+
+```mermaid
+sequenceDiagram
+ participant UI as Primary Adapter (Controller)
+ participant IP as Input Port (Interface)
+ participant Domain as Core Domain (Use Case)
+ participant OP as Output Port (Interface)
+ participant DB as Secondary Adapter (Repository)
+
+ UI->>IP: Invoke Execute(Command)
+ IP->>Domain: Transform Command to Domain Logic
+ Domain->>OP: Request Data (findById)
+ OP->>DB: Perform SQL/NoSQL Query
+ DB-->>OP: Return Entity State
+ OP-->>Domain: Return Entity
+ Domain->>Domain: Apply Business Invariants
+ Domain->>OP: Save New State (save)
+ OP->>DB: Persist Changes
+ DB-->>OP: Ack
+ OP-->>Domain: Success
+ Domain-->>IP: Return Result/DTO
+ IP-->>UI: Form HTTP/RPC Response
+```
+
+## β Boundary Constraints (Data Flow Rules)
+
+1. **No External Imports in Domain:** The Core Domain must NEVER import code from an Adapter (e.g., `import { PostgresDB } from '../adapters/db'`). It only implements Interfaces.
+2. **Adapter Injection:** Adapters are injected into the Domain (typically during app startup) via the Output Ports (Interfaces).
+3. **Primary vs Secondary:**
+ - Primary Adapters (Driving) call the Domain (Input Ports). Examples: REST Controllers, CLI scripts, Event Listeners.
+ - Secondary Adapters (Driven) are called by the Domain (Output Ports). Examples: Database Repositories, SMTP Clients, External API clients.
+4. **Data Translation:** Data must be mapped at the boundary. Do not pass the internal DB Model directly out to the Primary Adapter. Use DTOs at the Ports.
diff --git a/architectures/hexagonal-architecture/folder-structure.md b/architectures/hexagonal-architecture/folder-structure.md
new file mode 100644
index 0000000..ba258b0
--- /dev/null
+++ b/architectures/hexagonal-architecture/folder-structure.md
@@ -0,0 +1,77 @@
+---
+description: Hexagonal Architecture Folder Structure rules. Defining the exact directory blueprints for Ports and Adapters.
+technology: Hexagonal Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [best-practices, folder-structure, hexagonal-architecture, ports-and-adapters]
+ai_role: Senior Software Architect
+last_updated: 2026-03-22
+---
+
+# π Folder Structure Best Practices for Hexagonal Architecture
+
+
+ **Strict directory blueprints for zero-approval AI parsing.**
+
+
+---
+
+## π³ The Root Hierarchy
+
+A properly defined Hexagonal architecture clearly separates its concerns at the file-system level. AI Agents are expected to enforce this strict separation.
+
+```mermaid
+graph TD
+ Src[src/] --> Core[core/]
+ Src --> Adapters[adapters/]
+ Core --> Ports[ports/]
+ Core --> Domain[domain/]
+ Ports --> In[in/]
+ Ports --> Out[out/]
+ Adapters --> Primary[primary/]
+ Adapters --> Secondary[secondary/]
+
+ %% 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;
+ classDef layout fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000;
+
+ class Src component;
+ class Core component;
+ class Adapters component;
+ class Ports component;
+ class Domain component;
+```
+
+## ποΈ Example Directory Content
+
+```text
+src/
+βββ π core/ # The Heart of the System (No External Tech)
+β βββ π domain/ # Entities, Value Objects, Business Rules
+β β βββ User.ts
+β β βββ AccountId.ts
+β βββ π ports/ # Interfaces defining interactions
+β βββ π in/ # Primary Ports (Use Cases / Commands)
+β β βββ CreateUserUseCase.ts
+β βββ π out/ # Secondary Ports (SPIs / Repositories)
+β βββ UserRepositoryPort.ts
+β βββ EmailSenderPort.ts
+βββ π adapters/ # Concrete implementations
+ βββ π primary/ # Entry Points (Driving Adapters)
+ β βββ π http/ # REST Controllers / Express Routes
+ β β βββ UserController.ts
+ β βββ π cli/ # Console Commands
+ βββ π secondary/ # Exit Points (Driven Adapters)
+ βββ π database/ # ORMs (TypeORM, Prisma)
+ β βββ PostgresUserRepository.ts
+ βββ π external/ # 3rd Party APIs (SendGrid, Stripe)
+ βββ SendGridEmailSender.ts
+```
+
+## β Boundary Constraints
+
+1. **Isolation in `core/`:** Code inside `core/` is forbidden from importing modules from `adapters/`.
+2. **Implementation in `adapters/`:** Code inside `adapters/` relies heavily on implementing the interfaces declared in `core/ports/`.
+3. **Primary vs Secondary File Naming:** Append descriptive suffixes to Adapters to clarify intent (e.g., `PostgresUserRepository`, `StripePaymentService`).
diff --git a/architectures/hexagonal-architecture/implementation-guide.md b/architectures/hexagonal-architecture/implementation-guide.md
new file mode 100644
index 0000000..8cdd4fd
--- /dev/null
+++ b/architectures/hexagonal-architecture/implementation-guide.md
@@ -0,0 +1,170 @@
+---
+description: Hexagonal Architecture Implementation Guide rules. Defining the exact code constraints for Vibe Coding and AI.
+technology: Hexagonal Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [best-practices, implementation-guide, hexagonal-architecture, ports-and-adapters]
+ai_role: Senior Software Architect
+last_updated: 2026-03-22
+---
+
+# π οΈ Hexagonal Architecture Implementation Guide
+
+
+ **Executable blueprints and constraints for AI-agent code generation.**
+
+
+---
+
+## β‘ The Vibe Coding Instructions (Constraints)
+
+For any code generated within the Hexagonal Architecture ecosystem, the following boundaries must be strictly enforced:
+
+1. **Core Isolation (No External Imports):**
+ Code inside `src/core/domain/` or `src/core/ports/` must have **ZERO** imports from `src/adapters/` or any external UI/DB frameworks.
+
+2. **Strict Interface Fulfillment:**
+ Code in `src/adapters/secondary/` must implement interfaces declared in `src/core/ports/out/`. It acts as a bridge to external technologies (e.g., PostgreSQL, SendGrid).
+
+3. **Boundary DTO Translation:**
+ Adapters must map raw external data (HTTP Requests, Database Rows) into pure Domain Entities before passing them inward. When returning data, Domain Entities must be translated back into Adapter-specific DTOs before reaching the outside world. Do not leak the Core Entity to an HTTP response directly.
+
+---
+
+## π» Concrete Code Examples
+
+### 𧩠Entity Relationships (Class Diagram)
+
+```mermaid
+classDiagram
+ class User {
+ -String _id
+ -String _email
+ -String _status
+ +constructor(id, email)
+ +id() String
+ +email() String
+ +deactivate() void
+ }
+
+ class UserRepositoryPort {
+ <>
+ +findById(id: String) Promise~User~
+ +save(user: User) Promise~void~
+ }
+
+ class DeactivateUserUseCase {
+ -UserRepositoryPort userRepository
+ +execute(userId: String) Promise~void~
+ }
+
+ class PostgresUserRepository {
+ +findById(id: String) Promise~User~
+ +save(user: User) Promise~void~
+ }
+
+ DeactivateUserUseCase --> UserRepositoryPort : Uses
+ PostgresUserRepository ..|> UserRepositoryPort : Implements
+ UserRepositoryPort ..> User : Returns/Receives
+```
+
+### β
Best Practice: Core Domain (`src/core/domain/User.ts`)
+
+```typescript
+// Pure domain object - No framework annotations like @Entity or @Table
+export class User {
+ private readonly _id: string;
+ private _email: string;
+ private _status: 'ACTIVE' | 'INACTIVE';
+
+ constructor(id: string, email: string) {
+ this._id = id;
+ this._email = email;
+ this._status = 'ACTIVE';
+ }
+
+ public get id(): string { return this._id; }
+ public get email(): string { return this._email; }
+
+ public deactivate(): void {
+ this._status = 'INACTIVE';
+ }
+}
+```
+
+### β
Best Practice: Output Port (`src/core/ports/out/UserRepositoryPort.ts`)
+
+```typescript
+// Interface defined by the Domain to specify its needs from a DB
+import { User } from '../../domain/User';
+
+export interface UserRepositoryPort {
+ findById(id: string): Promise;
+ save(user: User): Promise;
+}
+```
+
+### β
Best Practice: Secondary Adapter (`src/adapters/secondary/database/PostgresUserRepository.ts`)
+
+```typescript
+// Adapter implementing the Port using an ORM (e.g., TypeORM or Prisma)
+import { UserRepositoryPort } from '../../../core/ports/out/UserRepositoryPort';
+import { User } from '../../../core/domain/User';
+import { db } from '../../../infrastructure/db'; // Imaginary DB client
+import { UserMapper } from './UserMapper'; // Maps DB Row to Domain Entity
+
+export class PostgresUserRepository implements UserRepositoryPort {
+ async findById(id: string): Promise {
+ const rawRow = await db.query('SELECT * FROM users WHERE id = $1', [id]);
+ if (!rawRow) return null;
+ return UserMapper.toDomain(rawRow);
+ }
+
+ async save(user: User): Promise {
+ await db.query('INSERT INTO users(id, email, status) VALUES($1, $2, $3)', [
+ user.id, user.email, user.status
+ ]);
+ }
+}
+```
+
+### β
Best Practice: Use Case / Input Port (`src/core/ports/in/DeactivateUserUseCase.ts`)
+
+```typescript
+import { UserRepositoryPort } from '../out/UserRepositoryPort';
+
+export class DeactivateUserUseCase {
+ constructor(private readonly userRepository: UserRepositoryPort) {}
+
+ async execute(userId: string): Promise {
+ const user = await this.userRepository.findById(userId);
+ if (!user) throw new Error('User not found');
+
+ user.deactivate(); // Business Rule application
+
+ await this.userRepository.save(user); // Persist state
+ }
+}
+```
+
+### β
Best Practice: Primary Adapter (`src/adapters/primary/http/UserController.ts`)
+
+```typescript
+// HTTP Controller invoking the Use Case
+import { Request, Response } from 'express';
+import { DeactivateUserUseCase } from '../../../core/ports/in/DeactivateUserUseCase';
+
+export class UserController {
+ constructor(private readonly deactivateUserUseCase: DeactivateUserUseCase) {}
+
+ async deactivate(req: Request, res: Response) {
+ try {
+ await this.deactivateUserUseCase.execute(req.params.id);
+ res.status(200).send({ message: 'User deactivated successfully' });
+ } catch (error) {
+ res.status(400).send({ error: error.message });
+ }
+ }
+}
+```
diff --git a/architectures/hexagonal-architecture/readme.md b/architectures/hexagonal-architecture/readme.md
new file mode 100644
index 0000000..7f4fa36
--- /dev/null
+++ b/architectures/hexagonal-architecture/readme.md
@@ -0,0 +1,41 @@
+---
+description: Hexagonal Architecture (Ports & Adapters) production-ready guidelines and modular breakdown for modern systems.
+technology: Hexagonal Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [best-practices, clean-code, hexagonal-architecture, ports-and-adapters, system-design, vibe-coding]
+ai_role: Senior Software Architect
+last_updated: 2026-03-22
+---
+
+# π Hexagonal Architecture Production-Ready Best Practices
+
+# 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
+
+
+
+
+ **Ports and Adapters for scalable, testable code.**
+
+ **Evaluating the return on investment when choosing Ports and Adapters.**
+
+
+---
+
+## π Pros & Cons Matrix
+
+| Feature | β
Pros | β Cons |
+| :--- | :--- | :--- |
+| **Testability** | Extreme isolate testing is native. Domain can run without a DB or UI. | Requires writing numerous Mock objects and Test Doubles. |
+| **Flexibility** | Swap out a DB (e.g., PostgreSQL for MongoDB) or Framework instantly. | Boilerplate heavy. Setup time for simple CRUD apps is unjustified. |
+| **Domain Focus** | Keeps the team focused strictly on business value logic. | Steep learning curve for Junior developers used to tight MVC coupling. |
+| **Delayed Decisions** | You don't need to pick a Database or UI Framework on day 1. | Over-engineering risk for startups seeking rapid MVP validation. |
+
+## β Hard Rules & Architectural Constraints
+
+1. **Dependency Inversion Enforcement:** The Core Domain must define its dependencies via Interfaces (Ports). It does not "call" Adapters. Adapters implement the Ports, and the application wiring (Dependency Injection container) provides the instances at runtime.
+2. **Framework Agnosticism in Core:** No ORM decorators (like `@Entity` or `@Column`) or Web Framework decorators (like `@Get` or `@Req`) are allowed inside `src/core/domain`.
+3. **Data Mapping Requirement:** Adapters must translate specific Data Objects (e.g., HTTP requests, DB rows) into clean Domain Entities before passing them inward. When returning data, Domain Entities must be translated back into Adapter-specific DTOs before reaching the outside world.
+4. **Ports Exclusivity:** A Port belongs to the Core Domain. The Core dictates what the Port looks like based on its business needs, not based on what a specific Adapter provides. An external library API should never dictate a Port's signature.
+
+## π When to use Hexagonal Architecture
+
+- **Use when:** The project is expected to live for 5+ years, undergoes frequent changes in external vendor tools, requires high test coverage, and involves complex business rules.
+- **Do not use when:** You are building a quick prototype, a purely data-driven CRUD application where the DB schema *is* the domain model, or if the engineering team is highly inexperienced with SOLID principles.
diff --git a/architectures/readme.md b/architectures/readme.md
index 4d6c193..1f0e9ad 100644
--- a/architectures/readme.md
+++ b/architectures/readme.md
@@ -55,6 +55,7 @@ Below are the most popular architectural patterns along with examples, tips, tec
**Description:** A modern architectural methodology for Frontend applications. It separates code by business meaning (features) and technical layers. It ensures strict unidirectional isolation.
+**π Map of Patterns:** [Go to FSD Guidelines](./feature-sliced-design/readme.md)
**Architecture Diagram & Folder Tree:**
```mermaid
@@ -139,6 +140,7 @@ src/
[](#)
**Description:** The classic design pattern for user-facing applications. It separates data logic (`Model`), presentation (`View`), and user action handling (`Controller`).
+**π Map of Patterns:** [Go to MVC Guidelines](./model-view-controller/readme.md)
**Architecture Diagram & Folder Tree:**
```mermaid
@@ -222,6 +224,7 @@ microservices-cluster/
[](#)
**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).
+**π Map of Patterns:** [Go to Hexagonal Architecture Guidelines](./hexagonal-architecture/readme.md)
**Architecture Diagram & Folder Tree:**
```mermaid