Diagrams as Code

Sometimes describing your architecture as code is a better fit than using a visual editor - especially for complex systems, version control, or CI/CD integration. Revision supports both approaches and they work together seamlessly. You can create diagrams as code and then refine them in the visual editor, or vice versa.

:::tip API Reference For complete documentation on the template endpoint, including all available properties and options, see the Template API reference. :::

:::info Component Types Types help identify what kind of component you're working with (database, application, service, etc.) and provide visual icons. You can use hundreds of built-in types or create custom ones. Find the right typeId slug for your components in our Type IDs reference. :::

Example: Database Schema Architecture

Here's a complete example showing how to define a complex database schema architecture using YAML:

curl -X POST https://your-workspace.revision.app/api/external/template \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/yaml" \
  -d 'YOUR_YAML_MODEL'

Example YAML model:

components:
  - ref: users-table # Stored reference for upsert behavior
    name: Users
    desc: Login credentials, email, status
    typeId: dmy2wCqStyC # Built-in table type slug

  - ref: profiles-table
    name: User Profiles
    desc: Personal info, preferences, settings
    typeId: dmy2wCqStyC

  - ref: orders-table
    name: Orders
    desc: Purchase records, totals, timestamps
    typeId: dmy2wCqStyC

  - ref: order-items-table
    name: Order Items
    desc: Quantity, price, product reference
    typeId: dmy2wCqStyC

  - ref: products-table
    name: Products
    desc: SKU, name, price, inventory count
    typeId: dmy2wCqStyC

  - ref: categories-table
    name: Categories
    desc: Product groupings and hierarchy
    typeId: dmy2wCqStyC

  - ref: reviews-table
    name: Reviews
    desc: Ratings, comments, timestamps
    typeId: dmy2wCqStyC

  - ref: addresses-table
    name: Addresses
    desc: Shipping and billing addresses
    typeId: dmy2wCqStyC

  - ref: payments-table
    name: Payments
    desc: Transaction records, payment methods
    typeId: dmy2wCqStyC

diagrams:
  - ref: ecommerce-schema # Stored reference for upsert behavior
    name: E-commerce Database Schema
    desc: Complete database schema showing relationships between core entities
    state: ACTIVE
    level: C1
    componentInstances:
      - ref: users-instance # Instance reference
        component: users-table # References component by ref

      - ref: profiles-instance
        component: profiles-table

      - ref: orders-instance
        component: orders-table

      - ref: order-items-instance
        component: order-items-table

      - ref: products-instance
        component: products-table

      - ref: categories-instance
        component: categories-table

      - ref: reviews-instance
        component: reviews-table

      - ref: addresses-instance
        component: addresses-table

      - ref: payments-instance
        component: payments-table

    relations:
      - fromComponentInstance: profiles-instance
        toComponentInstance: users-instance
        label: "Extends user data"
        desc: "One profile per user account"

      - fromComponentInstance: orders-instance
        toComponentInstance: users-instance
        label: "Placed by user"
        desc: "User can have multiple orders"

      - fromComponentInstance: order-items-instance
        toComponentInstance: orders-instance
        label: "Line item of"
        desc: "Items are part of an order"

      - fromComponentInstance: order-items-instance
        toComponentInstance: products-instance
        label: "References product"
        desc: "Each item references a product"

      - fromComponentInstance: products-instance
        toComponentInstance: categories-instance
        label: "Categorized as"
        desc: "Products are organized in categories"

      - fromComponentInstance: reviews-instance
        toComponentInstance: products-instance
        label: "Reviews product"
        desc: "Reviews are for specific products"

      - fromComponentInstance: reviews-instance
        toComponentInstance: users-instance
        label: "Written by user"
        desc: "Users write product reviews"

      - fromComponentInstance: addresses-instance
        toComponentInstance: users-instance
        label: "Belongs to user"
        desc: "User can have multiple addresses"

      - fromComponentInstance: payments-instance
        toComponentInstance: orders-instance
        label: "Payment for order"
        desc: "Each order has payment record"