Add Mermaid diagrams

guides/deployment/cicd.md

@@ -128,6 +128,54 @@ The release will show up in your _Releases_ page and a deployment to your produc
 
 <span id="afterstart" />
 
+### CI/CD Pipeline Architecture
+
+The following diagram shows the typical CI/CD pipeline flow for CAP applications using Hyperspace and Deploy with Confidence:
+
+```mermaid
+graph TD
+    A[Source Repository] --> B[Hyperspace Pipeline]
+    B --> C[Build & Unit Tests]
+    C --> D[Security Scans]
+    D --> E{Deploy Strategy}
+
+    E -->|Standard| F[Direct CF Deploy]
+    E -->|DwC| G[Deploy with Confidence]
+
+    F --> H[Integration Tests]
+    G --> I[DwC Staging Environment]
+
+    I --> J[Feature Toggle Tests]
+    J --> K[End-to-End Tests]
+    K --> L[Production Deployment]
+
+    H --> M[Staging Environment]
+    M --> N[User Acceptance Tests]
+    N --> O[Production Deployment]
+
+    L --> P[Health Monitoring]
+    O --> P
+    P --> Q[Operational Dashboards]
+
+    style A fill:#EFF4F9,stroke:#427CAC,color:#333
+    style B fill:#427CAC,stroke:#3F5161,color:#FFF
+    style C fill:#EFF4F9,stroke:#427CAC,color:#333
+    style D fill:#EFF4F9,stroke:#427CAC,color:#333
+    style E fill:#91C8F6,stroke:#427CAC,color:#333
+    style F fill:#427CAC,stroke:#3F5161,color:#FFF
+    style G fill:#427CAC,stroke:#3F5161,color:#FFF
+    style H fill:#EFF4F9,stroke:#427CAC,color:#333
+    style I fill:#FAFAFA,stroke:#BFBFBF,color:#333
+    style J fill:#EFF4F9,stroke:#427CAC,color:#333
+    style K fill:#EFF4F9,stroke:#427CAC,color:#333
+    style L fill:#ABE2AB,stroke:#2B7D2B,color:#333
+    style M fill:#FAFAFA,stroke:#BFBFBF,color:#333
+    style N fill:#EFF4F9,stroke:#427CAC,color:#333
+    style O fill:#ABE2AB,stroke:#2B7D2B,color:#333
+    style P fill:#E5E5E5,stroke:#666666,color:#333
+    style Q fill:#E5E5E5,stroke:#666666,color:#333
+```
+
 <span id="beforecicd" />
 
 ## SAP Continuous Integration and Delivery

guides/extensibility/customization.md

@@ -1074,3 +1074,139 @@ Adding data only for the missing columns doesn't work when using SAP HANA as a d
 :::
 
 <span id="afterAddingData" />
+
+Here is a sequence diagram that illustrates the draft creation and activation flow:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant ExtensionApp as OData Service
+    participant Database
+
+    Client->>+ExtensionApp: POST /orders/x_Customers (Payload)
+    Note right of Client: 1. Create a new customer draft
+    ExtensionApp->>+Database: INSERT into Customers_drafts
+    Database-->>-ExtensionApp: Confirm insertion
+    ExtensionApp-->>-Client: 201 Created (Draft Record)
+
+    Client->>+ExtensionApp: POST /orders/x_Customers(...)/draftActivate
+    Note right of Client: 2. Activate the draft
+    ExtensionApp->>+Database: INSERT into Customers from drafts table
+    Database-->>-ExtensionApp: Confirm insertion
+    ExtensionApp->>+Database: DELETE from Customers_drafts
+    Database-->>-ExtensionApp: Confirm deletion
+    ExtensionApp-->>-Client: 200 OK (Active Record)
+```
+
+### Extensibility Data Model
+
+The following entity relationship diagram shows how custom extensions relate to the base data model:
+
+```mermaid
+erDiagram
+    Orders ||--o{ Customers : "has customer"
+    Customers ||--|| x_Customers : "extends"
+    Orders ||--o{ x_SalesRegion : "assigned to region"
+    x_Customers ||--o{ x_SalesRegion : "belongs to region"
+
+    Orders {
+        UUID ID PK
+        Timestamp createdAt
+        String createdBy
+        UUID customer_ID FK
+        String regionCode FK
+    }
+
+    Customers {
+        UUID ID PK
+        String email
+        String firstName
+        String lastName
+        Timestamp createdAt
+        String createdBy
+    }
+
+    x_Customers {
+        UUID ID PK "Same as Customers.ID"
+        String creditCardNo
+        Date dateOfBirth
+        String status "platinum, gold, silver"
+        Integer creditScore
+        String regionCode FK
+    }
+
+    x_SalesRegion {
+        String regionCode PK
+        String name
+        String description
+        Boolean isActive
+    }
+```
+
+This diagram illustrates the key extensibility patterns:
+- **Extension entities** (`x_Customers`) share the same primary key as base entities (`Customers`)
+- **New entities** (`x_SalesRegion`) can be referenced by both base and extension entities
+- **Foreign key relationships** maintain referential integrity across the extended model
+
+### Extensibility Class Structure
+
+This class diagram provides a structural view of the extensibility patterns, showing inheritance and composition relationships:
+
+```mermaid
+classDiagram
+    namespace BaseModel {
+        class Orders {
+            +UUID ID
+            +Timestamp createdAt
+            +String createdBy
+            +UUID customer_ID
+            +String regionCode
+            +getCustomer()
+            +getRegion()
+        }
+
+        class Customers {
+            +UUID ID
+            +String email
+            +String firstName  
+            +String lastName
+            +Timestamp createdAt
+            +String createdBy
+            +getFullName()
+            +isActive()
+        }
+    }
+
+    namespace Extensions {
+        class x_Customers {
+            +UUID ID
+            +String creditCardNo
+            +Date dateOfBirth
+            +String status
+            +Integer creditScore
+            +String regionCode
+            +calculateAge()
+            +updateCreditScore()
+        }
+
+        class x_SalesRegion {
+            +String regionCode
+            +String name
+            +String description
+            +Boolean isActive
+            +getCustomers()
+            +activate()
+            +deactivate()
+        }
+    }
+
+    Orders ||--o{ Customers : "customer"
+    Customers ||--|| x_Customers : "extends"
+    Orders ||--o{ x_SalesRegion : "region"
+    x_Customers ||--o{ x_SalesRegion : "region"
+```
+
+Key aspects of this extensibility pattern:
+- **Shared Identity**: `x_Customers` uses the same primary key as `Customers`
+- **Composition over Inheritance**: Extensions complement rather than replace base functionality
+- **Cross-references**: New entities can be referenced by both base and extension entities

guides/extensibility/feature-toggles.md

@@ -135,6 +135,26 @@ Note the following limitations for `.cds` files in features:
 
 In principle, features can be toggled per request, per user, or per tenant; most commonly they'll be toggled per tenant, as demonstrated in the following.
 
+### Feature Toggle Lifecycle
+
+This state diagram illustrates the typical lifecycle of a feature toggle from development to production cleanup:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Development
+    Development --> Testing: Feature Complete
+    Testing --> Staging: Tests Pass
+    Staging --> ProductionOff: Deploy
+    ProductionOff --> ProductionOn: Toggle Enable
+    ProductionOn --> ProductionOff: Toggle Disable
+    ProductionOff --> Canary: Gradual Rollout
+    Canary --> ProductionOn: Success
+    Canary --> ProductionOff: Rollback
+    ProductionOn --> Deprecated: Mark for Removal
+    Deprecated --> Removed: Cleanup
+    Removed --> [*]
+```
+
 ### In Development
 
 <div class="impl node">

guides/multitenancy/index.md

@@ -1070,6 +1070,89 @@ Alternatively, overriding the [`dependencies`](./mtxs#get-dependencies) handler
 
 <div id="subscriptiondashboard" />
 
+### Tenant Subscription Flow
+
+The following diagram shows the complete tenant subscription and provisioning process:
+
+```mermaid
+flowchart TD
+    A[Tenant Subscribe Request] --> B{Service Type?}
+    B -->|SaaS Registry| C[SaaS Provisioning]
+    B -->|SMS| D[SMS Provisioning]
+
+    C --> E[Create HDI Container]
+    D --> F[Create HANA Tenant]
+
+    E --> G[Deploy Database Schema]
+    F --> G
+
+    G --> H[Initialize Tenant Data]
+    H --> I[Configure Security]
+    I --> J[Activate Subscription]
+    J --> K[Tenant Ready]
+
+    K --> L[Tenant Operations]
+    L --> M{Unsubscribe?}
+    M -->|No| L
+    M -->|Yes| N[Cleanup Resources]
+    N --> O[Remove HDI Container/HANA Tenant]
+    O --> P[Delete Subscription]
+    P --> Q[End]
+
+    style K fill:#90EE90,stroke:#4CAF50,color:#000
+    style A fill:#EFF4F9,stroke:#427CAC,color:#333
+    style B fill:#91C8F6,stroke:#427CAC,color:#333
+    style C fill:#427CAC,stroke:#3F5161,color:#FFF
+    style D fill:#427CAC,stroke:#3F5161,color:#FFF
+    style E fill:#EFF4F9,stroke:#427CAC,color:#333
+    style F fill:#EFF4F9,stroke:#427CAC,color:#333
+    style G fill:#91C8F6,stroke:#427CAC,color:#333
+    style H fill:#FAFAFA,stroke:#BFBFBF,color:#333
+    style I fill:#FAFAFA,stroke:#BFBFBF,color:#333
+    style J fill:#91C8F6,stroke:#427CAC,color:#333
+    style L fill:#FAFAFA,stroke:#BFBFBF,color:#333
+    style M fill:#BFBFBF,stroke:#666666,color:#333
+    style N fill:#E5E5E5,stroke:#666666,color:#333
+    style O fill:#E5E5E5,stroke:#666666,color:#333
+    style P fill:#E5E5E5,stroke:#666666,color:#333
+    style Q fill:#CCCCCC,stroke:#666666,color:#333
+```
+
+### Tenant Onboarding Experience
+
+This user journey flowchart maps the complete tenant onboarding experience from initial subscription to productive usage:
+
+```mermaid
+flowchart TD
+    A[Tenant Requests Subscription] --> B[Provider Reviews Request]
+    B --> C[Subscription Approved]
+    C --> D[Tenant Receives Access]
+
+    D --> E[First Login]
+    E --> F[Configure Basic Settings]
+    F --> G[Setup Authentication]
+
+    G --> H[Create User Accounts]
+    H --> I[Assign Roles & Permissions]
+    I --> J[Send User Invitations]
+
+    J --> K[Import Initial Data]
+    K --> L[Test Core Functions]
+    L --> M[Production Ready]
+    M --> N[Active Usage]
+
+    style A fill:#e3f2fd,stroke:#1976d2,color:#000
+    style C fill:#c8e6c9,stroke:#4caf50,color:#000
+    style M fill:#c8e6c9,stroke:#4caf50,color:#000
+    style N fill:#4caf50,stroke:#2e7d32,color:#fff
+
+    classDef adminTask fill:#fff3e0,stroke:#ff9800,color:#000
+    classDef userTask fill:#fce4ec,stroke:#e91e63,color:#000
+
+    class B,F,G,H,I,J adminTask
+    class E,K,L userTask
+```
+
 ## Add Custom Handlers
 
 MTX services are implemented as standard CAP services, so you can register for events just as you would for any application service.

guides/multitenancy/mtxs.md

@@ -1414,6 +1414,38 @@ The job and task status can take on the values `QUEUED`, `RUNNING`, `FINISHED` a
 
 <span id="sms-provisioning-service" />
 
+### MTXS Sidecar Communication Flow
+
+The following sequence diagram illustrates the interaction between the main application, MTX sidecar, and external services during tenant operations:
+
+```mermaid
+sequenceDiagram
+    participant App as CAP Application
+    participant Sidecar as MTX Sidecar
+    participant SMS as Subscription Manager
+    participant DB as Database Service
+    participant Auth as Auth Service
+
+    SMS->>+Sidecar: POST /tenant/{id} (Subscribe)
+    Note right of SMS: Tenant subscription request
+
+    Sidecar->>+DB: Create HDI Container
+    DB-->>-Sidecar: Container Created
+
+    Sidecar->>+DB: Deploy Schema Extensions
+    DB-->>-Sidecar: Deployment Complete
+
+    Sidecar->>+Auth: Setup Tenant Authentication
+    Auth-->>-Sidecar: Auth Configured
+
+    Sidecar->>+App: Tenant Provisioned Event
+    App-->>-Sidecar: Event Processed
+
+    Sidecar-->>-SMS: 201 Created (Tenant Ready)
+
+    Note over App,SMS: Tenant is now operational
+```
+
 ## [Old MTX Reference](old-mtx-apis) {.toc-redirect}
 
 [See Reference docs for former 'old' MTX Services.](old-mtx-apis){.learn-more}