Skip to main content
Last updated on by jmsrpp

Diagram Best Practices

This guide provides best practices for creating and contributing diagrams to the SAP Architecture Center. It covers Draw.io diagrams for SAP solution architectures and Mermaid diagrams for flow-based visualizations. Follow these guidelines to ensure your diagrams are consistent, visually appealing, and easy to understand.

Draw.io Diagrams for SAP BTP Solution Architectures​

When to Use Draw.io​

Use Draw.io diagrams when:

  • Representing SAP BTP services, cloud products, or technical landscapes.
  • Creating high-level solution architectures that include SAP services, environments, and their interdependencies.
  • Following the SAP BTP Solution Diagram Guidelines to ensure consistency and adherence to SAP design principles.

Best Practices for Draw.io Diagrams​

  1. Use the SAP BTP Starter Kit:

    • Download the SAP BTP Solution Diagram Starter Kit for official icons, templates, and design elements.
    • The starter kit includes pre-configured libraries, reusable templates, and examples to help you get started quickly.

  2. Leverage Shape Libraries and Editable Presets:

    • Access the Draw.io Shape Libraries for foundational icons, integration suite icons, and more.
    • Use the Editable Diagram Examples to explore reusable templates for common SAP BTP scenarios, such as:
      • SAP Build Work Zone (L2)
      • SAP Private Link Service (L2)
      • SAP Cloud Identity Services - Authentication (L2)

  3. Maintain Consistency:

    • Level 1 (L1) diagrams: Provide a high-level overview of solution architectures, focusing on key components and their relationships.
    • Level 2 (L2) diagrams: Offer detailed technical representations, including service interactions, data flows, and integration points.
    • Use the same icon sizes, line styles, and text formatting across all diagrams.
    • Avoid creating custom arrows; use the ones provided in the starter kit.

  4. Optimize for Readability:

    • Use Level 1 or Level 2 diagrams for detailed technical representations.

  5. Follow Repository Structure:

    • Place .drawio files in the drawio/ folder and refer to them in your markdown as in the Components reference.
    • Example structure: 
      ref-arch/
      ├─ RAXXXX/
      │  ├─ drawio/
      │  │  ├─ solution-diagram-1.drawio

Mermaid Diagrams for Flow-Based Visualizations​

When to Use Mermaid​

Use Mermaid diagrams when:

  • Representing process flows, decision trees, or data workflows.
  • Visualizing non-product-specific flows or abstract concepts.
  • Creating lightweight diagrams directly in markdown files.
Note

Mermaid-generated svg is automatically optimized for static websites. It is typically 10x-100x smaller than Drawio-generated svg. If you're trying to represent a simple flow, use Mermaid.

Best Practices for Mermaid Diagrams​

Check the code behind these examples by reviewing the underlying markdown, using the edit button at the top of this page. The rendered versions are displayed below for illustrative purposes.

  1. Choose the Right Diagram Type:

    • Use flowcharts for processes and workflows.
    • Use sequence diagrams for interactions between components.

  2. Use Styling for Consistency:

    • Apply classDef to define consistent styles for nodes and edges.
    • Example:

  3. Keep Layouts Intuitive:

    • Use subgraph to group related nodes and reduce clutter.
    • Example:

  4. Optimize for the Architecture Center:

    • Use smaller fonts and reduced stroke widths to ensure diagrams render well in the deployed site.
    • Example:

  5. Annotate Reverse Flows:

    • Use dashed lines (-.->) for reverse flows and add labels for clarity.
    • Example:

Examples from the Repository​

Drawio diagram examples​

  1. SAP Business Data Cloud and SAP Databricks
  • File: docs/ref-arch/RA0013/4-sap-databricks-in-business-data-cloud/drawio/bdc-databricks.drawio
  • Description: A diagram illustrating the capabilities of SAP Databricks within SAP Business Data Cloud.
  1. Edge Integration Cell on AWS
  • File: docs/ref-arch/RA0008/1-edge-integration-cell-on-aws/drawio/sap-edge-integration-cell-aws.drawio
  • Description: A diagram showing the deployment of SAP Integration Suite - Edge Integration Cell on AWS.
  1. Azure Data Integration
  • File: docs/ref-arch/RA0004/2-azure-data-integration/drawio/azure-data-integration.drawio
  • Description: A diagram illustrating data integration between SAP and Azure services.

Mermaid diagram examples​

Check the code behind these examples by reviewing the underlying markdown, using the edit button at the top of this page. The rendered versions are displayed below for illustrative purposes.

  1. Contribution Workflow

    • File: community/intro.md
    • Description: A flowchart showing the contribution process for the SAP Architecture Center. This diagram represents the decision-making process for contributing new or modified content. It illustrates how to reduce the size of nodes and edges in a long top to bottom flowchart by defining and applying a custom class.
    • Code:

  2. Insight Apps Data Flow

    • File: docs/ref-arch/RA0013/3-insight-apps-by-sap/readme.md
    • Description: A flowchart showing how raw source data is enriched through SAP Business Data Cloud components and surfaced in Insight Apps. It demonstrates how to use subgraphs for logical grouping of components.
    • Code:

  3. Contributor Lifecycle

    • File: community/Guidelines/contribution.md
    • Description: A Git graph showing the lifecycle of contributor changes in the SAP Architecture Center repository.
    • Code: