From adeee5f400feafa647372ff1bc6629f6fdd8185b Mon Sep 17 00:00:00 2001 From: Test User Date: Fri, 31 Jul 2026 17:51:24 +0530 Subject: [PATCH 1/2] docs: live CALM diagrams in learn tutorials (2-page demo) The complete-architecture beginner page now renders the e-commerce architecture the learner builds (including the composed-of platform boundary as a nested container), and the business-flows page animates the order-processing flow over it. Both diagrams are generated at build time from committed .calm.json files, so a broken tutorial architecture fails the site build. Demo scoped to two pages to gather feedback before extending to the full learn track. Signed-off-by: Test User --- .../beginner/07-complete-architecture.md | 11 + .../ecommerce-platform.calm.json | 307 ++++++++++++++++ .../intermediate/09-business-flows.md | 11 + .../ecommerce-platform-with-flow.calm.json | 344 ++++++++++++++++++ 4 files changed, 673 insertions(+) create mode 100644 docs/docs/tutorials/beginner/architectures/ecommerce-platform.calm.json create mode 100644 docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json diff --git a/docs/docs/tutorials/beginner/07-complete-architecture.md b/docs/docs/tutorials/beginner/07-complete-architecture.md index a8c50271b..acd49f467 100644 --- a/docs/docs/tutorials/beginner/07-complete-architecture.md +++ b/docs/docs/tutorials/beginner/07-complete-architecture.md @@ -4,6 +4,9 @@ title: "Build a Complete Architecture" sidebar_position: 7 --- +import { CalmDiagram } from '@finos/calm-docusaurus-plugin' + + # Build a Complete E-Commerce Microservice Architecture 🟢 **Difficulty:** Beginner | ⏱️ **Time:** 45-60 minutes @@ -550,6 +553,14 @@ calm validate -a architectures/ecommerce-platform.json You should see no errors and no warnings. ::: +## See What You Built + +This is the architecture you have been building through this tutorial, rendered live from the same kind of `.calm.json` file you just wrote. It is generated at build time from [`ecommerce-platform.calm.json`](./architectures/ecommerce-platform.calm.json) — zoom, pan, and click nodes for details. Notice the platform boundary drawn as a box: that is the `composed-of` relationship, rendered as real containment. + + + +If your file validates, it will render exactly like this. A broken file fails the site build — architecture diagrams in docs can never silently drift from the model. + ## Resources - [CALM Schema Reference](https://calm.finos.org/release/1.2/meta/calm.json) diff --git a/docs/docs/tutorials/beginner/architectures/ecommerce-platform.calm.json b/docs/docs/tutorials/beginner/architectures/ecommerce-platform.calm.json new file mode 100644 index 000000000..8ca3cf320 --- /dev/null +++ b/docs/docs/tutorials/beginner/architectures/ecommerce-platform.calm.json @@ -0,0 +1,307 @@ +{ + "$schema": "https://calm.finos.org/release/1.2/meta/calm.json", + "metadata": { + "owner": "platform-team@example.com", + "version": "1.0.0", + "created": "2026-01-09", + "description": "E-commerce order processing platform", + "tags": [ + "ecommerce", + "microservices", + "orders" + ], + "status": "production" + }, + "nodes": [ + { + "unique-id": "customer", + "node-type": "actor", + "name": "Customer", + "description": "End user who browses products and places orders" + }, + { + "unique-id": "admin", + "node-type": "actor", + "name": "Admin", + "description": "Administrator who manages inventory and monitors orders" + }, + { + "unique-id": "api-gateway", + "node-type": "service", + "name": "API Gateway", + "description": "Public entry point for all client requests, handles routing and authentication", + "interfaces": [ + { + "unique-id": "gateway-https", + "protocol": "HTTPS", + "host": "api.ecommerce.example.com", + "port": 443 + } + ], + "metadata": { + "tech-owner": "platform-team@example.com", + "repository": "https://github.com/example/api-gateway", + "deployment-type": "kubernetes", + "sla-tier": "tier-1" + } + }, + { + "unique-id": "order-service", + "node-type": "service", + "name": "Order Service", + "description": "Manages order lifecycle from creation to fulfillment", + "interfaces": [ + { + "unique-id": "order-api", + "protocol": "HTTPS", + "port": 8080 + } + ], + "metadata": { + "tech-owner": "orders-team@example.com", + "repository": "https://github.com/example/order-service", + "deployment-type": "kubernetes" + } + }, + { + "unique-id": "inventory-service", + "node-type": "service", + "name": "Inventory Service", + "description": "Tracks product stock levels and availability", + "interfaces": [ + { + "unique-id": "inventory-api", + "protocol": "HTTPS", + "port": 8081 + } + ], + "metadata": { + "tech-owner": "inventory-team@example.com", + "repository": "https://github.com/example/inventory-service", + "deployment-type": "kubernetes" + } + }, + { + "unique-id": "payment-service", + "node-type": "service", + "name": "Payment Service", + "description": "Processes payment transactions securely", + "interfaces": [ + { + "unique-id": "payment-api", + "protocol": "HTTPS", + "port": 8082 + } + ], + "metadata": { + "tech-owner": "payments-team@example.com", + "repository": "https://github.com/example/payment-service", + "deployment-type": "kubernetes", + "pci-compliant": true + } + }, + { + "unique-id": "order-database", + "node-type": "database", + "name": "Order Database", + "description": "PostgreSQL database storing order records and history", + "interfaces": [ + { + "unique-id": "order-db-jdbc", + "protocol": "JDBC", + "port": 5432 + } + ], + "metadata": { + "database-type": "PostgreSQL", + "version": "15", + "backup-frequency": "daily" + } + }, + { + "unique-id": "inventory-database", + "node-type": "database", + "name": "Inventory Database", + "description": "PostgreSQL database storing product inventory levels", + "interfaces": [ + { + "unique-id": "inventory-db-jdbc", + "protocol": "JDBC", + "port": 5433 + } + ], + "metadata": { + "database-type": "PostgreSQL", + "version": "15", + "backup-frequency": "daily" + } + }, + { + "unique-id": "ecommerce-platform", + "node-type": "system", + "name": "E-Commerce Platform", + "description": "Complete e-commerce order processing system" + } + ], + "relationships": [ + { + "unique-id": "customer-to-gateway", + "description": "Customer accesses the platform through the API Gateway", + "relationship-type": { + "interacts": { + "actor": "customer", + "nodes": [ + "api-gateway" + ] + } + } + }, + { + "unique-id": "admin-to-gateway", + "description": "Admin accesses the platform through the API Gateway", + "relationship-type": { + "interacts": { + "actor": "admin", + "nodes": [ + "api-gateway" + ] + } + } + }, + { + "unique-id": "gateway-to-orders", + "description": "API Gateway routes order requests to Order Service", + "relationship-type": { + "connects": { + "source": { + "node": "api-gateway", + "interfaces": [ + "gateway-https" + ] + }, + "destination": { + "node": "order-service", + "interfaces": [ + "order-api" + ] + } + } + }, + "metadata": { + "latency-sla": "100ms", + "protocol": "REST" + } + }, + { + "unique-id": "gateway-to-inventory", + "description": "API Gateway routes inventory requests to Inventory Service", + "relationship-type": { + "connects": { + "source": { + "node": "api-gateway", + "interfaces": [ + "gateway-https" + ] + }, + "destination": { + "node": "inventory-service", + "interfaces": [ + "inventory-api" + ] + } + } + }, + "metadata": { + "latency-sla": "100ms", + "protocol": "REST" + } + }, + { + "unique-id": "orders-to-database", + "description": "Order Service persists order data to the database", + "relationship-type": { + "connects": { + "source": { + "node": "order-service", + "interfaces": [ + "order-api" + ] + }, + "destination": { + "node": "order-database", + "interfaces": [ + "order-db-jdbc" + ] + } + } + }, + "metadata": { + "connection-pool-size": 20 + } + }, + { + "unique-id": "orders-to-payment", + "description": "Order Service calls Payment Service to process payments", + "relationship-type": { + "connects": { + "source": { + "node": "order-service", + "interfaces": [ + "order-api" + ] + }, + "destination": { + "node": "payment-service", + "interfaces": [ + "payment-api" + ] + } + } + }, + "metadata": { + "latency-sla": "500ms", + "retry-policy": "exponential-backoff" + } + }, + { + "unique-id": "inventory-to-database", + "description": "Inventory Service persists stock data to the database", + "relationship-type": { + "connects": { + "source": { + "node": "inventory-service", + "interfaces": [ + "inventory-api" + ] + }, + "destination": { + "node": "inventory-database", + "interfaces": [ + "inventory-db-jdbc" + ] + } + } + }, + "metadata": { + "connection-pool-size": 20 + } + }, + { + "unique-id": "platform-composition", + "description": "E-Commerce Platform contains all services and databases", + "relationship-type": { + "composed-of": { + "container": "ecommerce-platform", + "nodes": [ + "api-gateway", + "order-service", + "inventory-service", + "payment-service", + "order-database", + "inventory-database" + ] + } + } + } + ] +} diff --git a/docs/docs/tutorials/intermediate/09-business-flows.md b/docs/docs/tutorials/intermediate/09-business-flows.md index ef89b4a99..63bd8821f 100644 --- a/docs/docs/tutorials/intermediate/09-business-flows.md +++ b/docs/docs/tutorials/intermediate/09-business-flows.md @@ -4,6 +4,9 @@ title: "Model Business Flows" sidebar_position: 3 --- +import { CalmDiagram } from '@finos/calm-docusaurus-plugin' + + # Model Business Flows 🟡 **Difficulty:** Intermediate | ⏱️ **Time:** 30-45 minutes @@ -163,6 +166,14 @@ The same relationship can appear multiple times in a flow with different directi - Generating sequence diagrams for documentation - Attaching compliance controls to a specific process +## See the Flow Live + +Here is the order-processing flow you just modelled, animated over the e-commerce architecture. The moving dots trace each transition in sequence — including the reverse `destination-to-source` transition for the payment confirmation. Nodes and connections outside the flow are dimmed. + + + +The diagram is rendered from [`ecommerce-platform-with-flow.calm.json`](./architectures/ecommerce-platform-with-flow.calm.json), the same architecture from the beginner track with the `flows` array added exactly as described above. + ## Resources - [CALM Flow Schema](https://github.com/finos/architecture-as-code/blob/main/calm/release/1.2/meta/flow.json) diff --git a/docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json b/docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json new file mode 100644 index 000000000..450aff50e --- /dev/null +++ b/docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json @@ -0,0 +1,344 @@ +{ + "$schema": "https://calm.finos.org/release/1.2/meta/calm.json", + "metadata": { + "owner": "platform-team@example.com", + "version": "1.0.0", + "created": "2026-01-09", + "description": "E-commerce order processing platform", + "tags": [ + "ecommerce", + "microservices", + "orders" + ], + "status": "production" + }, + "nodes": [ + { + "unique-id": "customer", + "node-type": "actor", + "name": "Customer", + "description": "End user who browses products and places orders" + }, + { + "unique-id": "admin", + "node-type": "actor", + "name": "Admin", + "description": "Administrator who manages inventory and monitors orders" + }, + { + "unique-id": "api-gateway", + "node-type": "service", + "name": "API Gateway", + "description": "Public entry point for all client requests, handles routing and authentication", + "interfaces": [ + { + "unique-id": "gateway-https", + "protocol": "HTTPS", + "host": "api.ecommerce.example.com", + "port": 443 + } + ], + "metadata": { + "tech-owner": "platform-team@example.com", + "repository": "https://github.com/example/api-gateway", + "deployment-type": "kubernetes", + "sla-tier": "tier-1" + } + }, + { + "unique-id": "order-service", + "node-type": "service", + "name": "Order Service", + "description": "Manages order lifecycle from creation to fulfillment", + "interfaces": [ + { + "unique-id": "order-api", + "protocol": "HTTPS", + "port": 8080 + } + ], + "metadata": { + "tech-owner": "orders-team@example.com", + "repository": "https://github.com/example/order-service", + "deployment-type": "kubernetes" + } + }, + { + "unique-id": "inventory-service", + "node-type": "service", + "name": "Inventory Service", + "description": "Tracks product stock levels and availability", + "interfaces": [ + { + "unique-id": "inventory-api", + "protocol": "HTTPS", + "port": 8081 + } + ], + "metadata": { + "tech-owner": "inventory-team@example.com", + "repository": "https://github.com/example/inventory-service", + "deployment-type": "kubernetes" + } + }, + { + "unique-id": "payment-service", + "node-type": "service", + "name": "Payment Service", + "description": "Processes payment transactions securely", + "interfaces": [ + { + "unique-id": "payment-api", + "protocol": "HTTPS", + "port": 8082 + } + ], + "metadata": { + "tech-owner": "payments-team@example.com", + "repository": "https://github.com/example/payment-service", + "deployment-type": "kubernetes", + "pci-compliant": true + } + }, + { + "unique-id": "order-database", + "node-type": "database", + "name": "Order Database", + "description": "PostgreSQL database storing order records and history", + "interfaces": [ + { + "unique-id": "order-db-jdbc", + "protocol": "JDBC", + "port": 5432 + } + ], + "metadata": { + "database-type": "PostgreSQL", + "version": "15", + "backup-frequency": "daily" + } + }, + { + "unique-id": "inventory-database", + "node-type": "database", + "name": "Inventory Database", + "description": "PostgreSQL database storing product inventory levels", + "interfaces": [ + { + "unique-id": "inventory-db-jdbc", + "protocol": "JDBC", + "port": 5433 + } + ], + "metadata": { + "database-type": "PostgreSQL", + "version": "15", + "backup-frequency": "daily" + } + }, + { + "unique-id": "ecommerce-platform", + "node-type": "system", + "name": "E-Commerce Platform", + "description": "Complete e-commerce order processing system" + } + ], + "relationships": [ + { + "unique-id": "customer-to-gateway", + "description": "Customer accesses the platform through the API Gateway", + "relationship-type": { + "interacts": { + "actor": "customer", + "nodes": [ + "api-gateway" + ] + } + } + }, + { + "unique-id": "admin-to-gateway", + "description": "Admin accesses the platform through the API Gateway", + "relationship-type": { + "interacts": { + "actor": "admin", + "nodes": [ + "api-gateway" + ] + } + } + }, + { + "unique-id": "gateway-to-orders", + "description": "API Gateway routes order requests to Order Service", + "relationship-type": { + "connects": { + "source": { + "node": "api-gateway", + "interfaces": [ + "gateway-https" + ] + }, + "destination": { + "node": "order-service", + "interfaces": [ + "order-api" + ] + } + } + }, + "metadata": { + "latency-sla": "100ms", + "protocol": "REST" + } + }, + { + "unique-id": "gateway-to-inventory", + "description": "API Gateway routes inventory requests to Inventory Service", + "relationship-type": { + "connects": { + "source": { + "node": "api-gateway", + "interfaces": [ + "gateway-https" + ] + }, + "destination": { + "node": "inventory-service", + "interfaces": [ + "inventory-api" + ] + } + } + }, + "metadata": { + "latency-sla": "100ms", + "protocol": "REST" + } + }, + { + "unique-id": "orders-to-database", + "description": "Order Service persists order data to the database", + "relationship-type": { + "connects": { + "source": { + "node": "order-service", + "interfaces": [ + "order-api" + ] + }, + "destination": { + "node": "order-database", + "interfaces": [ + "order-db-jdbc" + ] + } + } + }, + "metadata": { + "connection-pool-size": 20 + } + }, + { + "unique-id": "orders-to-payment", + "description": "Order Service calls Payment Service to process payments", + "relationship-type": { + "connects": { + "source": { + "node": "order-service", + "interfaces": [ + "order-api" + ] + }, + "destination": { + "node": "payment-service", + "interfaces": [ + "payment-api" + ] + } + } + }, + "metadata": { + "latency-sla": "500ms", + "retry-policy": "exponential-backoff" + } + }, + { + "unique-id": "inventory-to-database", + "description": "Inventory Service persists stock data to the database", + "relationship-type": { + "connects": { + "source": { + "node": "inventory-service", + "interfaces": [ + "inventory-api" + ] + }, + "destination": { + "node": "inventory-database", + "interfaces": [ + "inventory-db-jdbc" + ] + } + } + }, + "metadata": { + "connection-pool-size": 20 + } + }, + { + "unique-id": "platform-composition", + "description": "E-Commerce Platform contains all services and databases", + "relationship-type": { + "composed-of": { + "container": "ecommerce-platform", + "nodes": [ + "api-gateway", + "order-service", + "inventory-service", + "payment-service", + "order-database", + "inventory-database" + ] + } + } + } + ], + "flows": [ + { + "unique-id": "order-processing-flow", + "name": "Customer Order Processing", + "description": "End-to-end flow from customer placing an order to payment confirmation", + "transitions": [ + { + "relationship-unique-id": "customer-to-gateway", + "sequence-number": 1, + "description": "Customer submits order via web interface", + "summary": "Customer submits order via web interface", + "direction": "source-to-destination" + }, + { + "relationship-unique-id": "gateway-to-orders", + "sequence-number": 2, + "description": "Gateway routes the order to the order service", + "summary": "Gateway routes the order to the order service", + "direction": "source-to-destination" + }, + { + "relationship-unique-id": "orders-to-payment", + "sequence-number": 3, + "description": "Order service requests payment authorisation", + "summary": "Order service requests payment authorisation", + "direction": "source-to-destination" + }, + { + "relationship-unique-id": "orders-to-payment", + "sequence-number": 4, + "description": "Payment service returns confirmation", + "summary": "Payment service returns confirmation", + "direction": "destination-to-source" + } + ] + } + ] +} \ No newline at end of file From 6f24997acad43deddbede9cb120714cd91addd1a Mon Sep 17 00:00:00 2001 From: Test User Date: Mon, 3 Aug 2026 16:56:26 +0530 Subject: [PATCH 2/2] docs: match demo flows to the tutorial's own definitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The order-processing flow now carries exactly the three transitions the tutorial defines in step 2 (the demo previously added a reverse leg the tutorial does not teach), and the Inventory Stock Check flow from step 4 is rendered as its own diagram — the tutorial's actual bi-directional example, with transitions 4 and 5 reusing relationships in destination-to-source direction. Addresses feedback on #2928. Signed-off-by: Test User --- .../intermediate/09-business-flows.md | 10 ++-- .../ecommerce-platform-with-flow.calm.json | 49 ++++++++++++++++--- 2 files changed, 49 insertions(+), 10 deletions(-) diff --git a/docs/docs/tutorials/intermediate/09-business-flows.md b/docs/docs/tutorials/intermediate/09-business-flows.md index 63bd8821f..6af5a6142 100644 --- a/docs/docs/tutorials/intermediate/09-business-flows.md +++ b/docs/docs/tutorials/intermediate/09-business-flows.md @@ -166,13 +166,17 @@ The same relationship can appear multiple times in a flow with different directi - Generating sequence diagrams for documentation - Attaching compliance controls to a specific process -## See the Flow Live +## See the Flows Live -Here is the order-processing flow you just modelled, animated over the e-commerce architecture. The moving dots trace each transition in sequence — including the reverse `destination-to-source` transition for the payment confirmation. Nodes and connections outside the flow are dimmed. +Here is the order-processing flow you modelled in step 2, animated over the e-commerce architecture — three transitions, in sequence, with everything outside the flow dimmed: -The diagram is rendered from [`ecommerce-platform-with-flow.calm.json`](./architectures/ecommerce-platform-with-flow.calm.json), the same architecture from the beginner track with the `flows` array added exactly as described above. +And here is the inventory stock check from step 4 — watch the dots on the inventory-service connections travel **both ways**: steps 4 and 5 reuse the same relationships with `destination-to-source`, exactly the request-response pattern this tutorial teaches: + + + +Both diagrams render from [`ecommerce-platform-with-flow.calm.json`](./architectures/ecommerce-platform-with-flow.calm.json), the beginner-track architecture with the two flows added exactly as described above. ## Resources diff --git a/docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json b/docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json index 450aff50e..100f6809c 100644 --- a/docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json +++ b/docs/docs/tutorials/intermediate/architectures/ecommerce-platform-with-flow.calm.json @@ -320,22 +320,57 @@ { "relationship-unique-id": "gateway-to-orders", "sequence-number": 2, - "description": "Gateway routes the order to the order service", - "summary": "Gateway routes the order to the order service", + "description": "API Gateway routes order to Order Service", + "summary": "API Gateway routes order to Order Service", "direction": "source-to-destination" }, { "relationship-unique-id": "orders-to-payment", "sequence-number": 3, - "description": "Order service requests payment authorisation", - "summary": "Order service requests payment authorisation", + "description": "Order Service initiates payment processing", + "summary": "Order Service initiates payment processing", + "direction": "source-to-destination" + } + ] + }, + { + "unique-id": "inventory-check-flow", + "name": "Inventory Stock Check", + "description": "Admin checks and updates inventory stock levels", + "transitions": [ + { + "relationship-unique-id": "admin-to-gateway", + "sequence-number": 1, + "description": "Admin requests inventory status", + "summary": "Admin requests inventory status", "direction": "source-to-destination" }, { - "relationship-unique-id": "orders-to-payment", + "relationship-unique-id": "gateway-to-inventory", + "sequence-number": 2, + "description": "Route to inventory service", + "summary": "Route to inventory service", + "direction": "source-to-destination" + }, + { + "relationship-unique-id": "inventory-to-database", + "sequence-number": 3, + "description": "Query current stock levels", + "summary": "Query current stock levels", + "direction": "source-to-destination" + }, + { + "relationship-unique-id": "inventory-to-database", "sequence-number": 4, - "description": "Payment service returns confirmation", - "summary": "Payment service returns confirmation", + "description": "Return stock data", + "summary": "Return stock data", + "direction": "destination-to-source" + }, + { + "relationship-unique-id": "gateway-to-inventory", + "sequence-number": 5, + "description": "Return inventory report", + "summary": "Return inventory report", "direction": "destination-to-source" } ]