docs: autonomous visual synthesis

README_AUTONOMY.md

@@ -44,6 +44,22 @@ To maximize the value of the $300 Google Cloud free tier/credits, follow these b
 4. **Monitoring:**
    - Use the [Google Cloud Console Billing](https://console.cloud.google.com/billing) to set alerts at 50%, 75%, and 90% of credit usage.
    - Check Vertex AI "Quotas & System Limits" to ensure no unexpected spikes in usage.
+
+```mermaid
+graph LR
+    Step1[1. Selective Triggering] --> Step2[2. Model Selection]
+    Step2 --> Step3[3. Storage Lifecycle]
+    Step3 --> Step4[4. Monitoring]
+
+    classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+
+    class Step1 component
+    class Step2 component
+    class Step3 component
+    class Step4 component
+```
+
 ## Setup Requirements
 Ensure the following GitHub Secrets are configured:
 - `GCP_SA_KEY`: Service Account JSON with Vertex AI User and Storage Admin roles.

architectures/backend-for-frontend/folder-structure.md

@@ -47,6 +47,35 @@ src/
 ├── config/
 └── index.ts
 ```
+```mermaid
+classDiagram
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+    classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
+    class Node1_src {
+        src/
+    }
+    cssClass "Node1_src" default
+    class Node2_handlers {
+        handlers/
+    }
+    Node1_src *-- Node2_handlers
+    cssClass "Node2_handlers" default
+    class Node3_userDashboardHandlertscontainsroutingbusinesslogicandAPIcalls {
+        userDashboardHandler.ts (contains routing, business logic, and API calls)
+    }
+    Node2_handlers *-- Node3_userDashboardHandlertscontainsroutingbusinesslogicandAPIcalls
+    cssClass "Node3_userDashboardHandlertscontainsroutingbusinesslogicandAPIcalls" component
+    class Node4_config {
+        config/
+    }
+    Node1_src *-- Node4_config
+    cssClass "Node4_config" default
+    class Node5_indexts {
+        index.ts
+    }
+    Node1_src *-- Node5_indexts
+    cssClass "Node5_indexts" component
+```
 
 ### ⚠️ Problem
 Placing routing, data aggregation, and downstream API calls in a single handler creates a monolithic structure within the BFF. It makes testing difficult, limits code reuse, and violates the single responsibility principle.

architectures/clean-architecture/trade-offs.md

@@ -19,3 +19,13 @@ last_updated: 2026-03-29
 ### Cons
 - Increased boilerplate and indirection.
 - Steep learning curve for beginners.
+
+### ⚖️ Structural Comparison: Pros vs Cons
+
+| Category | Point |
+| :--- | :--- |
+| ✅ **Pros** | High testability. |
+| ✅ **Pros** | Framework agnostic. |
+| ✅ **Pros** | Database agnostic. |
+| ❌ **Cons** | Increased boilerplate and indirection. |
+| ❌ **Cons** | Steep learning curve for beginners. |

architectures/cqrs/trade-offs.md

@@ -18,3 +18,12 @@ last_updated: 2026-03-29
 ### Cons
 - Eventual consistency complexity.
 - High architectural overhead for simple domains.
+
+### ⚖️ Structural Comparison: Pros vs Cons
+
+| Category | Point |
+| :--- | :--- |
+| ✅ **Pros** | Independent scaling of read and write workloads. |
+| ✅ **Pros** | Optimized data schemas for read vs write operations. |
+| ❌ **Cons** | Eventual consistency complexity. |
+| ❌ **Cons** | High architectural overhead for simple domains. |

architectures/domain-driven-design/trade-offs.md

@@ -18,3 +18,12 @@ last_updated: 2026-03-29
 ### Cons
 - Extreme overhead for CRUD operations.
 - Requires domain experts collaboration.
+
+### ⚖️ Structural Comparison: Pros vs Cons
+
+| Category | Point |
+| :--- | :--- |
+| ✅ **Pros** | Aligns code strictly with business realities. |
+| ✅ **Pros** | High focus on the core domain complexity. |
+| ❌ **Cons** | Extreme overhead for CRUD operations. |
+| ❌ **Cons** | Requires domain experts collaboration. |

architectures/event-sourcing/folder-structure.md

@@ -29,3 +29,62 @@ src/
 └── 📁 infrastructure/      # Event Store bindings, Repositories, Message Bus
     └── EventStoreRepository.ts
 ```
+```mermaid
+classDiagram
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+    classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
+    class Node1_src {
+        src/
+    }
+    cssClass "Node1_src" default
+    class Node2_commands {
+        commands/
+    }
+    Node1_src *-- Node2_commands
+    cssClass "Node2_commands" default
+    class Node3_CreateOrderCommandts {
+        CreateOrderCommand.ts
+    }
+    Node2_commands *-- Node3_CreateOrderCommandts
+    cssClass "Node3_CreateOrderCommandts" component
+    class Node4_events {
+        events/
+    }
+    Node1_src *-- Node4_events
+    cssClass "Node4_events" default
+    class Node5_OrderCreatedEventts {
+        OrderCreatedEvent.ts
+    }
+    Node4_events *-- Node5_OrderCreatedEventts
+    cssClass "Node5_OrderCreatedEventts" component
+    class Node6_aggregates {
+        aggregates/
+    }
+    Node1_src *-- Node6_aggregates
+    cssClass "Node6_aggregates" default
+    class Node7_OrderAggregatets {
+        OrderAggregate.ts
+    }
+    Node6_aggregates *-- Node7_OrderAggregatets
+    cssClass "Node7_OrderAggregatets" component
+    class Node8_projections {
+        projections/
+    }
+    Node1_src *-- Node8_projections
+    cssClass "Node8_projections" default
+    class Node9_OrderReadModelProjectorts {
+        OrderReadModelProjector.ts
+    }
+    Node8_projections *-- Node9_OrderReadModelProjectorts
+    cssClass "Node9_OrderReadModelProjectorts" component
+    class Node10_infrastructure {
+        infrastructure/
+    }
+    Node1_src *-- Node10_infrastructure
+    cssClass "Node10_infrastructure" default
+    class Node11_EventStoreRepositoryts {
+        EventStoreRepository.ts
+    }
+    Node10_infrastructure *-- Node11_EventStoreRepositoryts
+    cssClass "Node11_EventStoreRepositoryts" component
+```

architectures/feature-sliced-design/trade-offs.md

@@ -22,6 +22,18 @@ last_updated: 2026-03-29
 - **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).
 
+### ⚖️ Structural Comparison: Pros vs Cons
+
+| Category | Point |
+| :--- | :--- |
+| ✅ **Pros** | **High Cohesion & Low Coupling**: Modules are highly independent. |
+| ✅ **Pros** | **Scalability**: New features can be added without affecting existing ones. |
+| ✅ **Pros** | **Predictability**: Strict rules for dependencies make it easier to find and understand code. |
+| ✅ **Pros** | **Team Collaboration**: Standardized structure allows developers to quickly onboard. |
+| ❌ **Cons** | **Steep Learning Curve**: Strict rules require discipline and understanding from the team. |
+| ❌ **Cons** | **Overhead for Small Projects**: Can be overly complex for simple applications or MVPs. |
+| ❌ **Cons** | **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).

architectures/hexagonal-architecture/folder-structure.md

@@ -65,6 +65,115 @@ src/
         └── 📁 external/     # 3rd Party APIs (SendGrid, Stripe)
             └── SendGridEmailSender.ts
 ```
+```mermaid
+classDiagram
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+    classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
+    class Node1_src {
+        src/
+    }
+    cssClass "Node1_src" default
+    class Node2_core {
+        core/
+    }
+    Node1_src *-- Node2_core
+    cssClass "Node2_core" default
+    class Node3_domain {
+        domain/
+    }
+    Node2_core *-- Node3_domain
+    cssClass "Node3_domain" default
+    class Node4_Userts {
+        User.ts
+    }
+    Node3_domain *-- Node4_Userts
+    cssClass "Node4_Userts" component
+    class Node5_AccountIdts {
+        AccountId.ts
+    }
+    Node3_domain *-- Node5_AccountIdts
+    cssClass "Node5_AccountIdts" component
+    class Node6_ports {
+        ports/
+    }
+    Node2_core *-- Node6_ports
+    cssClass "Node6_ports" default
+    class Node7_in {
+        in/
+    }
+    Node6_ports *-- Node7_in
+    cssClass "Node7_in" default
+    class Node8_CreateUserUseCasets {
+        CreateUserUseCase.ts
+    }
+    Node7_in *-- Node8_CreateUserUseCasets
+    cssClass "Node8_CreateUserUseCasets" component
+    class Node9_out {
+        out/
+    }
+    Node6_ports *-- Node9_out
+    cssClass "Node9_out" default
+    class Node10_UserRepositoryPortts {
+        UserRepositoryPort.ts
+    }
+    Node9_out *-- Node10_UserRepositoryPortts
+    cssClass "Node10_UserRepositoryPortts" component
+    class Node11_EmailSenderPortts {
+        EmailSenderPort.ts
+    }
+    Node9_out *-- Node11_EmailSenderPortts
+    cssClass "Node11_EmailSenderPortts" component
+    class Node12_adapters {
+        adapters/
+    }
+    Node1_src *-- Node12_adapters
+    cssClass "Node12_adapters" default
+    class Node13_primary {
+        primary/
+    }
+    Node12_adapters *-- Node13_primary
+    cssClass "Node13_primary" default
+    class Node14_http {
+        http/
+    }
+    Node13_primary *-- Node14_http
+    cssClass "Node14_http" default
+    class Node15_UserControllerts {
+        UserController.ts
+    }
+    Node14_http *-- Node15_UserControllerts
+    cssClass "Node15_UserControllerts" component
+    class Node16_cli {
+        cli/
+    }
+    Node13_primary *-- Node16_cli
+    cssClass "Node16_cli" default
+    class Node17_secondary {
+        secondary/
+    }
+    Node12_adapters *-- Node17_secondary
+    cssClass "Node17_secondary" default
+    class Node18_database {
+        database/
+    }
+    Node17_secondary *-- Node18_database
+    cssClass "Node18_database" default
+    class Node19_PostgresUserRepositoryts {
+        PostgresUserRepository.ts
+    }
+    Node18_database *-- Node19_PostgresUserRepositoryts
+    cssClass "Node19_PostgresUserRepositoryts" component
+    class Node20_external {
+        external/
+    }
+    Node17_secondary *-- Node20_external
+    cssClass "Node20_external" default
+    class Node21_SendGridEmailSenderts {
+        SendGridEmailSender.ts
+    }
+    Node20_external *-- Node21_SendGridEmailSenderts
+    cssClass "Node21_SendGridEmailSenderts" component
+```
 ## ⛔ Boundary Constraints
 
 1. **Isolation in `core/`:** Code inside `core/` is forbidden from importing modules from `adapters/`.

architectures/micro-frontends/folder-structure.md

@@ -28,6 +28,35 @@ monorepo/
 │   ├── app-shell/
 │   ├── mfe-auth/ (imports directly from app-shell)
 ```
+```mermaid
+classDiagram
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+    classDef default fill:#e1f5fe,stroke:#03a9f4,stroke-width:2px,color:#000;
+    class Node1_monorepo {
+        monorepo/
+    }
+    cssClass "Node1_monorepo" default
+    class Node2_packages {
+        packages/
+    }
+    Node1_monorepo *-- Node2_packages
+    cssClass "Node2_packages" default
+    class Node3_shareduicontainsbusinesslogic {
+        shared-ui/ (contains business logic!)
+    }
+    Node2_packages *-- Node3_shareduicontainsbusinesslogic
+    cssClass "Node3_shareduicontainsbusinesslogic" component
+    class Node4_appshell {
+        app-shell/
+    }
+    Node2_packages *-- Node4_appshell
+    cssClass "Node4_appshell" default
+    class Node5_mfeauthimportsdirectlyfromappshell {
+        mfe-auth/ (imports directly from app-shell)
+    }
+    Node2_packages *-- Node5_mfeauthimportsdirectlyfromappshell
+    cssClass "Node5_mfeauthimportsdirectlyfromappshell" component
+```
 
 #### ⚠️ Problem
 Storing business logic in shared libraries or directly importing cross-package code defeats the purpose of micro-frontends. It binds deployment cycles together, meaning a change in `shared-ui` forces all dependent MFEs to re-test and redeploy simultaneously.

architectures/microservices/trade-offs.md

@@ -18,3 +18,12 @@ last_updated: 2026-03-29
 ### Cons
 - Distributed system complexity.
 - Difficult cross-service transactions.
+
+### ⚖️ Structural Comparison: Pros vs Cons
+
+| Category | Point |
+| :--- | :--- |
+| ✅ **Pros** | Independent scaling. |
+| ✅ **Pros** | Technological freedom per service. |
+| ❌ **Cons** | Distributed system complexity. |
+| ❌ **Cons** | Difficult cross-service transactions. |

architectures/model-view-controller/trade-offs.md

@@ -22,6 +22,18 @@ last_updated: 2026-03-29
 - **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.
 
+### ⚖️ Structural Comparison: Pros vs Cons
+
+| Category | Point |
+| :--- | :--- |
+| ✅ **Pros** | **Familiarity**: Easy to understand, widely adopted pattern. |
+| ✅ **Pros** | **Separation of Concerns**: Clear distinction between data, UI, and control logic. |
+| ✅ **Pros** | **Rapid Development**: Excellent for starting MVP applications. |
+| ✅ **Pros** | **Framework Support**: High support across many frameworks (Spring, Express, Rails, Django). |
+| ❌ **Cons** | **Scalability**: For very large apps, "fat controllers" and "fat models" become common. |
+| ❌ **Cons** | **Coupling**: Often strong coupling between view and controller. |
+| ❌ **Cons** | **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.

architectures/monolithic-architecture/trade-offs.md

@@ -18,3 +18,12 @@ last_updated: 2026-03-29
 ### Cons
 - Scales as a whole, not by component.
 - Large codebase can slow down IDEs and startup times.
+
+### ⚖️ Structural Comparison: Pros vs Cons
+
+| Category | Point |
+| :--- | :--- |
+| ✅ **Pros** | Easy to develop, test, and deploy. |
+| ✅ **Pros** | Strong transactional guarantees (ACID). |
+| ❌ **Cons** | Scales as a whole, not by component. |
+| ❌ **Cons** | Large codebase can slow down IDEs and startup times. |