diff --git a/agents.md b/agents.md
index b25435f..0f2877d 100644
--- a/agents.md
+++ b/agents.md
@@ -99,6 +99,18 @@ For extensions like Cloud Code or GitHub Copilot, append the contents of `AGENTS
 2.  **Constraint Identification:** Locate the specific `.md` file corresponding to the user's task (e.g., if the user asks for a NestJS service, read `backend/nestjs/readme.md`).
 3.  **Hierarchy Alignment:** Prioritize `architectures/` constraints over `frontend/` or `backend/` specifics to ensure structural integrity.
 4.  **Verification:** Before outputting code, run a "Constraint Check" against the identified rules to ensure zero violations of the "Best Practise" standard.
+
+```mermaid
+graph LR
+    Context[Context Discovery] --> Constraint[Constraint Identification]
+    Constraint --> Hierarchy[Hierarchy Alignment]
+    Hierarchy --> Verification[Verification]
+
+    classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+
+    class Context,Constraint,Hierarchy,Verification component;
+```
 ---
 ## 🔍 5. SEO & Discoverability
 <!--
diff --git a/architectures/event-sourcing/folder-structure.md b/architectures/event-sourcing/folder-structure.md
index ec30265..e8fbdba 100644
--- a/architectures/event-sourcing/folder-structure.md
+++ b/architectures/event-sourcing/folder-structure.md
@@ -29,3 +29,30 @@ src/
 └── 📁 infrastructure/      # Event Store bindings, Repositories, Message Bus
     └── EventStoreRepository.ts
 ```
+
+```mermaid
+classDiagram
+    class src {
+    }
+    class commands {
+        +CreateOrderCommand.ts
+    }
+    class events {
+        +OrderCreatedEvent.ts
+    }
+    class aggregates {
+        +OrderAggregate.ts
+    }
+    class projections {
+        +OrderReadModelProjector.ts
+    }
+    class infrastructure {
+        +EventStoreRepository.ts
+    }
+
+    src *-- commands
+    src *-- events
+    src *-- aggregates
+    src *-- projections
+    src *-- infrastructure
+```
diff --git a/backend/nestjs/readme.md b/backend/nestjs/readme.md
index 401a0f8..2dead6d 100644
--- a/backend/nestjs/readme.md
+++ b/backend/nestjs/readme.md
@@ -131,6 +131,16 @@ async createUser(@Body() dto: CreateDto) {
 ```
 ### ⚠️ Problem
 Failing to follow best practices for `fat controllers vs thin controllers` tightly couples dependencies and degrades predictability. This unstructured approach deviates from deterministic AI-coding standards, creating severe architectural debt and potential security vulnerabilities in enterprise scaling.
+
+### ⚖️ Structural Comparison: Fat Controllers vs Thin Controllers
+
+| Feature | Fat Controllers | Thin Controllers |
+| :--- | :--- | :--- |
+| **Business Logic** | Embedded in controller | Delegated to Service layer |
+| **Testability** | Hard (Requires mocking HTTP context) | Easy (Pure functions/methods) |
+| **Reusability** | Low (Tied to HTTP routes) | High (Can be called from CLI/Events) |
+| **Dependency Coupling** | High | Low |
+
 ### ✅ Best Practice
 ```typescript
 @Post()
diff --git a/docs/windsurf-vibe-coding-hints.md b/docs/windsurf-vibe-coding-hints.md
index 0a91773..9ec70b0 100644
--- a/docs/windsurf-vibe-coding-hints.md
+++ b/docs/windsurf-vibe-coding-hints.md
@@ -54,6 +54,18 @@ To make Windsurf AI agents generate perfect code, follow these simple rules for
 1. **Be Specific:** Tell the AI agent exactly which file to change. For example, say "Update the button component in `src/button.tsx`" instead of "Change the button".
 2. **Use Clear English:** Write your prompts in simple, direct language. Avoid using complex phrasing.
 3. **Limit the Context Window:** Close unnecessary files to keep the context window small and avoid reaching memory limits.
+
+```mermaid
+graph LR
+    Specific[Be Specific] --> Clear[Use Clear English]
+    Clear --> Limit[Limit Context Window]
+
+    classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+
+    class Specific,Clear,Limit component;
+```
+
 ## ✅ 5. Actionable Checklist for Windsurf Vibe Coding Success
 
 Follow these steps every time you start a new vibe coding session with Windsurf: