Skip to main content
Learn

Create Your First Node

⏱ 3 min read🟢 Beginner · 20-30 minutesEdit on GitHub ↗

Overview​

Use the CALM agent you configured in the previous tutorial to create your first architecture file with AI assistance.

Learning objectives​

By the end of this tutorial, you will:

  • Understand what a node represents in CALM
  • Create a valid CALM architecture JSON file
  • Use GitHub Copilot with the CALM agent
  • Validate your architecture using the CLI

Prerequisites​

Complete Setup & CLI first.

Step-by-Step Guide​

1. Understand What a Node Represents​

A node in CALM represents a distinct architectural component. CALM provides built-in node types, but also allows architects to define custom node types.

Built-in node types include:

  • actor: External users or systems
  • system: High-level business systems
  • service: Microservices or applications
  • database: Data storage systems
  • network: Network infrastructure
  • ldap: Directory services
  • webclient: Browser-based clients
  • data-asset: Data products or datasets

Custom node types: You can define your own (e.g., "message-queue", "cache", "api-gateway") to better represent your specific architecture.

2. Open the CALM Agent in VSCode​

  1. Open your calm-learning repository in VSCode
  2. Open the Copilot Chat panel:
    • Windows/Linux: Ctrl+Alt+I or click the chat icon in the sidebar
    • Mac: Cmd+Shift+I or click the chat icon in the sidebar
  3. Select the CALM agent:
    • Click the agent selector dropdown (shows "Agent" by default)
    • Select "CALM" from the list
    • The chat panel will now show "CALM" as the active mode

3. Use This Prompt with Copilot​

Copy and paste this prompt into the Copilot chat (customize the parts in [] brackets):

Create a new CALM architecture file at architectures/my-first-architecture.json

The architecture should contain a single node representing [describe a system you work with, e.g., "a payment processing service that handles credit card transactions"].

Use appropriate node-type, and include a meaningful unique-id, name, and description.

Make sure the file includes the correct $schema reference and validates against the CALM 1.2 specification.

Example customized prompt:

Create a new CALM architecture file at architectures/my-first-architecture.json

The architecture should contain a single node representing a customer authentication service that validates user credentials and manages session tokens.

Use appropriate node-type, and include a meaningful unique-id, name, and description.

Make sure the file includes the correct $schema reference and validates against the CALM 1.2 specification.

4. Review the AI's Output​

Copilot will generate the file. Important: Don't blindly accept it! Review and verify:

  • ✅ File is in the correct location: architectures/my-first-architecture.json
  • ✅ Contains $schema property pointing to the CALM 1.2 JSON schema
  • ✅ Has a nodes array with your node
  • ✅ Node has all required properties: unique-id, node-type, name, description
  • ✅ The node-type is appropriate for what you're modeling
  • ✅ The unique-id uses kebab-case (e.g., "auth-service" not "AuthService")

5. Validate Your Architecture​

calm validate -a architectures/my-first-architecture.json

If validation fails with errors:

  • Read the error message carefully
  • Ask Copilot to fix it: Fix the validation errors in architectures/my-first-architecture.json
  • Validate again
note

Warnings about nodes not being referenced in any relationship are fine — you only have one node so far.

6. Understand What Was Created​

Open the generated file and make sure you understand each part:

  • What does the $schema property do?
  • Why are there four required properties on a node?
  • What would happen if you changed the node-type?

Try this: Ask Copilot to explain:

Explain each property in the node I just created

Key concepts​

Node Structure​

A CALM node requires these properties:

{
  "unique-id": "auth-service",
  "node-type": "service",
  "name": "Authentication Service",
  "description": "Handles user authentication and session management"
}
PropertyPurpose
unique-idUnique identifier within the architecture (kebab-case)
node-typeCategory of component (service, database, actor, etc.)
nameHuman-readable display name
descriptionDetailed explanation of what this node represents

The $schema Property​

The $schema property tells validation tools which version of CALM to use:

{
  "$schema": "https://calm.finos.org/release/1.2/meta/calm.json",
  "nodes": [...],
  "relationships": []
}
note

A valid CALM architecture requires both nodes and relationships arrays at the top level, even if relationships is empty. Without the relationships array, validation will fail.

Resources​

Tips​

  • Use descriptive unique-id values — they should convey meaning
  • node-type should match the nature of the component
  • Write clear descriptions that help others understand the component's purpose
  • Always validate after making changes

Next steps​

In the next tutorial, you'll connect multiple nodes with relationships!