Learn

Model Business Flows

⏱ 2 min read🟡 Intermediate · 30-45 minutesTry in Learning Lab ↗Edit on GitHub ↗

Overview

Map business processes to technical architecture using flows, connecting business intent to implementation.

Learning objectives

By the end of this tutorial, you will:

Understand the structure of CALM flows and transitions
Create flows that trace business processes through your architecture
Use bidirectional transitions to model request-response patterns
Visualize flows as sequence diagrams in the VSCode extension
Optionally attach flow-level controls for compliance

Prerequisites

Complete the Beginner Tutorials section first. You will need your architectures/ecommerce-platform.json from the Build a Complete Architecture lesson.

Try in Learning Lab

You can work through this tutorial in your browser with the CALM Learning Lab. There is nothing to install: the lab runs the real CALM engine, and the calm commands this tutorial uses work as they do in the CLI. The lab has no AI assistant, so you write the CALM yourself instead of prompting Copilot.

Open this tutorial in the Learning Lab ↗

Step-by-Step Guide

1. Understand Flows

Flows consist of:

unique-id: Identifier for the flow
name: Business process name
description: What the flow represents
transitions: Ordered steps referencing relationships
- relationship-unique-id: Which connection is used
- sequence-number: Order in the flow (1, 2, 3…)
- description: What happens in this step
- direction: source-to-destination or destination-to-source

2. Map Your E-Commerce Order Flow

Open architectures/ecommerce-platform.json.

First, identify the relationship unique-ids from your Build a Complete Architecture architecture that form the order flow path:

Customer → API Gateway (interacts relationship)
API Gateway → Order Service (connects relationship)
Order Service → Payment Service (connects relationship)

Prompt:

Add a flows array at the top level of architectures/ecommerce-platform.json (after controls, before nodes).

Create a flow with:
- unique-id: "order-processing-flow"
- name: "Customer Order Processing"
- description: "End-to-end flow from customer placing an order to payment confirmation"
- transitions array referencing the ACTUAL relationship unique-ids from my architecture:
  1. The customer-to-gateway interacts relationship, sequence-number: 1, description: "Customer submits order via web interface", direction: "source-to-destination"
  2. The gateway-to-order-service connects relationship, sequence-number: 2, description: "API Gateway routes order to Order Service", direction: "source-to-destination"
  3. The order-service-to-payment-service connects relationship, sequence-number: 3, description: "Order Service initiates payment processing", direction: "source-to-destination"

Look up the exact relationship unique-ids from my relationships array and use those.

Note: Your relationship unique-ids may differ based on how Copilot named them in the Build a Complete Architecture lesson. The AI will look up your actual IDs.

3. Validate Flow Structure

calm validate -a architectures/ecommerce-platform.json

Should pass! ✅

4. Add a Second Flow: Inventory Stock Check

Prompt:

Add a second flow to the flows array in architectures/ecommerce-platform.json:

- unique-id: "inventory-check-flow"
- name: "Inventory Stock Check"
- description: "Admin checks and updates inventory stock levels"
- transitions using the ACTUAL relationship unique-ids from my architecture:
  1. Admin → API Gateway (interacts): "Admin requests inventory status", direction: "source-to-destination"
  2. API Gateway → Inventory Service (connects): "Route to inventory service", direction: "source-to-destination"
  3. Inventory Service → Inventory Database (connects): "Query current stock levels", direction: "source-to-destination"
  4. Inventory Database → Inventory Service (same relationship): "Return stock data", direction: "destination-to-source"
  5. Inventory Service → API Gateway (same relationship): "Return inventory report", direction: "destination-to-source"

Look up the exact relationship unique-ids from my relationships array.

Tip: Notice how steps 4 and 5 reuse the same relationships but with destination-to-source direction — this models the response flowing back.

5. Visualize Flows

Flows appear in the CALM Model Elements view and can be visualized as sequence diagrams.

Steps:

Save architectures/ecommerce-platform.json
Open the CALM Model Elements view in the sidebar
Expand the Flows section — you should see your two flows listed
Click on a flow (e.g., order-processing-flow)
The preview will show both the architecture diagram and a sequence diagram showing the flow's transitions in order

6. Add Flow Controls (Optional Advanced)

Flows can have their own controls. This example uses CALM's published control requirement schema, which requires control-id, name, and description. The logging and retention targets are illustrative. Validation checks this documentation; it does not enforce logging or retention in the running system.

Prompt:

Add a controls section to the order-processing-flow in architectures/ecommerce-platform.json:

Add an "audit" control with:
- description: "All order processing steps must be logged for audit compliance"
- requirements:
  - requirement-url: "https://calm.finos.org/release/1.2/meta/control-requirement.json"
    config (inline): { "control-id": "AUDIT-001", "name": "Transaction logging", "description": "Log all order processing steps in detail and retain logs for 365 days" }

Validate again after adding the flow control:

calm validate -a architectures/ecommerce-platform.json

Before continuing, take a moment to commit your changes using git. A clear commit message will help you track how your architecture has evolved.

Key concepts

Flow Structure

{
  "flows": [
    {
      "unique-id": "order-processing-flow",
      "name": "Customer Order Processing",
      "description": "End-to-end flow from order to payment",
      "transitions": [
        {
          "relationship-unique-id": "customer-to-gateway",
          "sequence-number": 1,
          "description": "Customer submits order",
          "direction": "source-to-destination"
        }
      ]
    }
  ]
}

Bidirectional Transitions

The same relationship can appear multiple times in a flow with different directions to model request-response:

{ "relationship-unique-id": "svc-to-db", "sequence-number": 3, "direction": "source-to-destination" },
{ "relationship-unique-id": "svc-to-db", "sequence-number": 4, "direction": "destination-to-source" }

When to Use Flows

Tracing a business capability end-to-end
Impact analysis ("which services are in my order flow?")
Generating sequence diagrams for documentation
Attaching compliance controls to a specific process

Resources

Next steps

In the next tutorial, you'll link Architecture Decision Records to your architecture to create traceability from decisions to implementation!

Overview​

◎Learning objectives​

✓Prerequisites​

▶Try in Learning Lab​

Step-by-Step Guide​

1. Understand Flows​

2. Map Your E-Commerce Order Flow​

3. Validate Flow Structure​

4. Add a Second Flow: Inventory Stock Check​

5. Visualize Flows​

6. Add Flow Controls (Optional Advanced)​

◆Key concepts​

Flow Structure​

Bidirectional Transitions​

When to Use Flows​

🔗Resources​

→Next steps​

Overview

Learning objectives

Prerequisites

Try in Learning Lab

Step-by-Step Guide

1. Understand Flows

2. Map Your E-Commerce Order Flow

3. Validate Flow Structure

4. Add a Second Flow: Inventory Stock Check

5. Visualize Flows

6. Add Flow Controls (Optional Advanced)

Key concepts

Flow Structure

Bidirectional Transitions

When to Use Flows

Resources

Next steps