From 953f8ae9dd06a49d18bfe84a8391721e9258e92d Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 17 May 2026 09:04:10 +0000 Subject: [PATCH] [docs: autonomous-visual-synthesis] Co-authored-by: beginwebdev2002 <102213457+beginwebdev2002@users.noreply.github.com> --- README_AUTONOMY.md | 16 +++ .../backend-for-frontend/folder-structure.md | 29 +++++ .../clean-architecture/trade-offs.md | 10 ++ architectures/cqrs/trade-offs.md | 9 ++ .../domain-driven-design/trade-offs.md | 9 ++ .../event-sourcing/folder-structure.md | 59 ++++++++++ .../feature-sliced-design/trade-offs.md | 12 ++ .../folder-structure.md | 109 ++++++++++++++++++ .../micro-frontends/folder-structure.md | 29 +++++ architectures/microservices/trade-offs.md | 9 ++ .../model-view-controller/trade-offs.md | 12 ++ .../monolithic-architecture/trade-offs.md | 9 ++ architectures/readme.md | 39 +++++++ architectures/serverless/trade-offs.md | 9 ++ .../folder-structure.md | 104 +++++++++++++++++ 15 files changed, 464 insertions(+) diff --git a/README_AUTONOMY.md b/README_AUTONOMY.md index 6ae5983..301ad9e 100644 --- a/README_AUTONOMY.md +++ b/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. diff --git a/architectures/backend-for-frontend/folder-structure.md b/architectures/backend-for-frontend/folder-structure.md index b5cd004..c9e0729 100644 --- a/architectures/backend-for-frontend/folder-structure.md +++ b/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. diff --git a/architectures/clean-architecture/trade-offs.md b/architectures/clean-architecture/trade-offs.md index bcf1866..dbd7a24 100644 --- a/architectures/clean-architecture/trade-offs.md +++ b/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. | diff --git a/architectures/cqrs/trade-offs.md b/architectures/cqrs/trade-offs.md index b0154d6..cf22ba0 100644 --- a/architectures/cqrs/trade-offs.md +++ b/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. | diff --git a/architectures/domain-driven-design/trade-offs.md b/architectures/domain-driven-design/trade-offs.md index 1f25125..63757a9 100644 --- a/architectures/domain-driven-design/trade-offs.md +++ b/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. | diff --git a/architectures/event-sourcing/folder-structure.md b/architectures/event-sourcing/folder-structure.md index ec30265..112770f 100644 --- a/architectures/event-sourcing/folder-structure.md +++ b/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 +``` diff --git a/architectures/feature-sliced-design/trade-offs.md b/architectures/feature-sliced-design/trade-offs.md index 7436641..fde317a 100644 --- a/architectures/feature-sliced-design/trade-offs.md +++ b/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). diff --git a/architectures/hexagonal-architecture/folder-structure.md b/architectures/hexagonal-architecture/folder-structure.md index 30f2dde..0d44fa3 100644 --- a/architectures/hexagonal-architecture/folder-structure.md +++ b/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/`. diff --git a/architectures/micro-frontends/folder-structure.md b/architectures/micro-frontends/folder-structure.md index 2e5133a..3e7e6c9 100644 --- a/architectures/micro-frontends/folder-structure.md +++ b/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. diff --git a/architectures/microservices/trade-offs.md b/architectures/microservices/trade-offs.md index 920956e..7ad64b3 100644 --- a/architectures/microservices/trade-offs.md +++ b/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. | diff --git a/architectures/model-view-controller/trade-offs.md b/architectures/model-view-controller/trade-offs.md index 6fc3dc2..16a0156 100644 --- a/architectures/model-view-controller/trade-offs.md +++ b/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. diff --git a/architectures/monolithic-architecture/trade-offs.md b/architectures/monolithic-architecture/trade-offs.md index 54fe095..3294643 100644 --- a/architectures/monolithic-architecture/trade-offs.md +++ b/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. | diff --git a/architectures/readme.md b/architectures/readme.md index 266a53a..4e2eb34 100644 --- a/architectures/readme.md +++ b/architectures/readme.md @@ -101,6 +101,45 @@ src/ ├── 📁 entities/ # Core business entities (User, Product) └── 📁 shared/ # Reusable code (UI-components, API, utils) ``` +```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_app { + app/ + } + Node1_src *-- Node2_app + cssClass "Node2_app" default + class Node3_pages { + pages/ + } + Node1_src *-- Node3_pages + cssClass "Node3_pages" default + class Node4_widgets { + widgets/ + } + Node1_src *-- Node4_widgets + cssClass "Node4_widgets" default + class Node5_features { + features/ + } + Node1_src *-- Node5_features + cssClass "Node5_features" default + class Node6_entities { + entities/ + } + Node1_src *-- Node6_entities + cssClass "Node6_entities" default + class Node7_shared { + shared/ + } + Node1_src *-- Node7_shared + cssClass "Node7_shared" default +``` **Best Compatibility:** - **Frameworks:** React, Vue, Angular diff --git a/architectures/serverless/trade-offs.md b/architectures/serverless/trade-offs.md index df01c09..e5f53a4 100644 --- a/architectures/serverless/trade-offs.md +++ b/architectures/serverless/trade-offs.md @@ -18,3 +18,12 @@ last_updated: 2026-03-29 ### Cons - Cold starts. - Vendor lock-in (AWS, GCP, Azure). + +### ⚖️ Structural Comparison: Pros vs Cons + +| Category | Point | +| :--- | :--- | +| ✅ **Pros** | Zero server management. | +| ✅ **Pros** | Scales to zero (cost effective). | +| ❌ **Cons** | Cold starts. | +| ❌ **Cons** | Vendor lock-in (AWS, GCP, Azure). | diff --git a/architectures/space-based-architecture/folder-structure.md b/architectures/space-based-architecture/folder-structure.md index deae6fb..7bf0c73 100644 --- a/architectures/space-based-architecture/folder-structure.md +++ b/architectures/space-based-architecture/folder-structure.md @@ -38,6 +38,110 @@ src/ ├── writers/ └── recovery/ ``` +```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_apigateway { + api-gateway/ + } + Node1_src *-- Node2_apigateway + cssClass "Node2_apigateway" default + class Node3_routes { + routes/ + } + Node2_apigateway *-- Node3_routes + cssClass "Node3_routes" default + class Node4_middleware { + middleware/ + } + Node2_apigateway *-- Node4_middleware + cssClass "Node4_middleware" default + class Node5_middleware { + middleware/ + } + Node1_src *-- Node5_middleware + cssClass "Node5_middleware" default + class Node6_loadbalancer { + load-balancer/ + } + Node5_middleware *-- Node6_loadbalancer + cssClass "Node6_loadbalancer" default + class Node7_datarouter { + data-router/ + } + Node5_middleware *-- Node7_datarouter + cssClass "Node7_datarouter" default + class Node8_processingunits { + processing-units/ + } + Node1_src *-- Node8_processingunits + cssClass "Node8_processingunits" default + class Node9_authunit { + auth-unit/ + } + Node8_processingunits *-- Node9_authunit + cssClass "Node9_authunit" default + class Node10_logic { + logic/ + } + Node9_authunit *-- Node10_logic + cssClass "Node10_logic" default + class Node11_dataaccess { + data-access/ + } + Node9_authunit *-- Node11_dataaccess + cssClass "Node11_dataaccess" default + class Node12_catalogunit { + catalog-unit/ + } + Node8_processingunits *-- Node12_catalogunit + cssClass "Node12_catalogunit" default + class Node13_logic { + logic/ + } + Node12_catalogunit *-- Node13_logic + cssClass "Node13_logic" default + class Node14_dataaccess { + data-access/ + } + Node12_catalogunit *-- Node14_dataaccess + cssClass "Node14_dataaccess" default + class Node15_datagrid { + data-grid/ + } + Node1_src *-- Node15_datagrid + cssClass "Node15_datagrid" default + class Node16_schemas { + schemas/ + } + Node15_datagrid *-- Node16_schemas + cssClass "Node16_schemas" default + class Node17_config { + config/ + } + Node15_datagrid *-- Node17_config + cssClass "Node17_config" default + class Node18_datapumps { + data-pumps/ + } + Node1_src *-- Node18_datapumps + cssClass "Node18_datapumps" default + class Node19_writers { + writers/ + } + Node18_datapumps *-- Node19_writers + cssClass "Node19_writers" default + class Node20_recovery { + recovery/ + } + Node18_datapumps *-- Node20_recovery + cssClass "Node20_recovery" default +``` ## Layering Logic