Ref-001: CALM (Common Architecture Language Model) DSL Specification

Type

Reference Documentation - Language Specification

Bounded Context

Architectural Governance

Purpose

Defines the CALM-based DSL for formally describing, validating, and governing enterprise architecture within SEA-Forge™. Based on the FINOS CALM standard, this specification enables Architecture-as-Code practices and automated architectural governance.

1. Introduction

The Common Architecture Language Model (CALM) provides a machine-readable blueprint for enterprise systems. Within SEA-Forge™’s Architectural Governance pillar, CALM serves as the formal language for defining architectural intent, enforcing constraints, and preventing drift.

Foundation Standard

FINOS CALM Project: https://github.com/finos/architecture-as-code
Specification: JSON/YAML-based architecture definition language

2. Core Principles

2.1. Architecture-as-Code

Architectural definitions are treated as code:

✅ Stored in version control (Git)
✅ Subject to code review and approval
✅ Versioned with semantic versioning
✅ Diff-able for change tracking
✅ Integrated into CI/CD pipelines

File Format: my-system.arch.json or my-system.arch.yaml

2.2. Declarative

Architects declare the desired state of the architecture (what it should be), not imperative steps (how to build it).

Example:

nodes:
  - id: payment-service
    type: service
    metadata:
      encryption: required

Not:

Create payment service
Enable encryption
Deploy to Kubernetes

2.3. Machine-Readable

The DSL is expressed in JSON (or YAML as a superset), enabling:

Programmatic parsing by automated tools
Validation against schemas
Transformation to other formats (diagrams, docs, IaC)
Integration with AI agents for reasoning

2.4. Extensible

The core CALM schema can be extended with custom metadata and controls to meet:

Organizational requirements
Regulatory compliance (GDPR, HIPAA, SOC2)
Industry-specific standards
Enterprise governance policies

2.5. Generative

The CALM DSL serves as input for generating:

✅ Architecture diagrams (C4, UML)
✅ Documentation (Markdown, HTML, PDF)
✅ Infrastructure-as-Code (Terraform, Kubernetes manifests)
✅ Compliance reports (control status, audit trails)
✅ Code scaffolding (service templates, API stubs)

3. CALM DSL Structure

A CALM document consists of four primary components:

{
  "nodes": [...],         // Architectural components
  "relationships": [...], // Component interactions
  "metadata": {...},      // Document-level properties
  "controls": [...]       // Governance policies
}

4. Nodes (Components)

Nodes represent the fundamental building blocks of the architecture.

4.1. Node Definition

{
  "nodes": [
    {
      "id": "order-service",
      "name": "Order Processing Service",
      "type": "service",
      "description": "Microservice responsible for handling customer orders.",
      "metadata": {
        "domain": "Sales",
        "team": "Alpha Squad",
        "language": "Python",
        "deployment": "Kubernetes"
      },
      "controls": [
        {
          "id": "data-encryption-at-rest",
          "description": "All persistent data must be encrypted at rest.",
          "status": "compliant"
        }
      ]
    }
  ]
}

4.2. Node Attributes

Attribute	Type	Required	Description
`id`	string	✅	Unique identifier (kebab-case recommended)
`name`	string	✅	Human-readable name
`type`	string	✅	Node categorization (see below)
`description`	string	❌	Detailed explanation of purpose
`metadata`	object	❌	Custom key-value attributes
`controls`	array	❌	Applicable governance policies

4.3. Node Types

Standard Types:

service - Microservice, API, backend service
database - Relational DB, NoSQL, graph database
queue - Message queue, event stream
external-api - Third-party API, SaaS integration
ui-component - Frontend application, web UI

SEA-Forge™ Extensions:

ai-agent - AI/ML service, LLM agent
cognitive-engine - Artifact generation, recommendation service
knowledge-graph - Oxigraph, semantic data store
dsl-runtime - CADSL renderer, SBVR processor

4.4. Metadata Examples

Domain Context:

"metadata": {
  "domain": "Sales",               // DDD Bounded Context
  "boundedContext": "OrderManagement",
  "aggregateRoot": "Order"
}

Team Ownership:

"metadata": {
  "team": "Alpha Squad",
  "owner": "john.doe@company.com",
  "oncall": "alpha-oncall@company.com"
}

Technology Stack:

"metadata": {
  "language": "Python",
  "framework": "FastAPI",
  "database": "PostgreSQL",
  "messageQueue": "RabbitMQ"
}

Deployment:

"metadata": {
  "deployment": "Kubernetes",
  "namespace": "production",
  "replicas": 3,
  "region": "us-east-1"
}

Data Classification:

"metadata": {
  "dataClassification": "PII",    // Personally Identifiable Information
  "complianceScope": ["GDPR", "HIPAA"]
}

Semantic Core Link:

"metadata": {
  "semanticCoreLink": "dsl://sales/OrderPolicy",
  "sbvrRules": ["order-minimum-value-rule"]
}

4.5. Controls on Nodes

Controls define governance requirements applicable to a node:

"controls": [
  {
    "id": "data-encryption-at-rest",
    "description": "All persistent data must be encrypted at rest.",
    "status": "compliant"
  },
  {
    "id": "multi-factor-authentication",
    "description": "Service authentication requires MFA.",
    "status": "non-compliant"
  },
  {
    "id": "penetration-testing-annual",
    "description": "Annual penetration testing required.",
    "status": "waived",
    "waiverReason": "No external exposure"
  }
]

Control Status Values:

compliant - Requirement is met
non-compliant - Violation detected
waived - Exception granted (requires reason)

5. Relationships (Interactions)

Relationships define how nodes interact with each other.

5.1. Relationship Definition

{
  "relationships": [
    {
      "id": "order-service-to-customer-db",
      "source": "order-service",
      "target": "customer-db",
      "type": "reads-writes",
      "description": "Order service reads and writes customer data.",
      "metadata": {
        "protocol": "JDBC",
        "encryption": "TLS 1.2"
      },
      "controls": [
        {
          "id": "access-control-least-privilege",
          "description": "Database access must adhere to least privilege principle.",
          "status": "compliant"
        }
      ]
    }
  ]
}

5.2. Relationship Attributes

Attribute	Type	Required	Description
`id`	string	✅	Unique identifier
`source`	string	✅	ID of originating node
`target`	string	✅	ID of destination node
`type`	string	✅	Interaction categorization
`description`	string	❌	Detailed explanation
`metadata`	object	❌	Custom attributes
`controls`	array	❌	Governance policies for interaction

5.3. Relationship Types

Data Access:

reads - Source reads from target
writes - Source writes to target
reads-writes - Bidirectional data access

Communication:

api-call - Synchronous HTTP/REST API
message-queue - Asynchronous message passing
stream - Real-time data streaming
event - Event-driven notification

SEA-Forge™ Extensions:

governs - Source enforces policies on target
informs - Source provides context to target
generates - Source creates instances of target

5.4. Relationship Metadata

Protocol & Security:

"metadata": {
  "protocol": "HTTPS",
  "encryption": "TLS 1.3",
  "authentication": "OAuth2",
  "authorization": "RBAC"
}

Data Flow:

"metadata": {
  "dataFlow": "PII",              // Data classification
  "dataVolume": "10GB/day",
  "latency": "< 100ms",
  "sla": "99.9%"
}

Network:

"metadata": {
  "networkZone": "private",
  "firewallRule": "fw-rule-123",
  "allowedPorts": [443, 8080]
}

5.5. Controls on Relationships

Controls for interactions (e.g., data-in-transit encryption):

"controls": [
  {
    "id": "data-in-transit-encryption",
    "description": "All network traffic must use TLS 1.2+",
    "status": "compliant"
  },
  {
    "id": "api-rate-limiting",
    "description": "External APIs must implement rate limiting",
    "status": "non-compliant"
  }
]

6. Complete Example: E-Commerce System

{
  "nodes": [
    {
      "id": "order-service",
      "name": "Order Processing Service",
      "type": "service",
      "description": "Handles customer order creation and management",
      "metadata": {
        "domain": "Sales",
        "team": "Alpha Squad",
        "language": "Python",
        "deployment": "Kubernetes",
        "semanticCoreLink": "dsl://sales/OrderAggregate"
      },
      "controls": [{ "id": "data-encryption", "status": "compliant" }]
    },
    {
      "id": "customer-db",
      "name": "Customer Database",
      "type": "database",
      "description": "PostgreSQL database storing customer profiles",
      "metadata": {
        "dataClassification": "PII",
        "owner": "Data Governance Team",
        "backup": "daily"
      },
      "controls": [
        { "id": "encryption-at-rest", "status": "compliant" },
        { "id": "access-logging", "status": "compliant" }
      ]
    },
    {
      "id": "payment-gateway",
      "name": "External Payment Gateway",
      "type": "external-api",
      "description": "Stripe payment processing API",
      "metadata": {
        "vendor": "Stripe",
        "dataFlow": "Financial"
      }
    }
  ],
  "relationships": [
    {
      "id": "order-to-customer-db",
      "source": "order-service",
      "target": "customer-db",
      "type": "reads-writes",
      "metadata": {
        "protocol": "JDBC",
        "encryption": "TLS 1.2"
      },
      "controls": [{ "id": "least-privilege", "status": "compliant" }]
    },
    {
      "id": "order-to-payment",
      "source": "order-service",
      "target": "payment-gateway",
      "type": "api-call",
      "metadata": {
        "protocol": "HTTPS",
        "authentication": "OAuth2",
        "dataFlow": "PII,Financial"
      },
      "controls": [{ "id": "pci-dss-compliance", "status": "compliant" }]
    }
  ]
}

7. Integration with SEA-Forge™

7.1. Semantic Core (DomainForge™ + SBVR)

CALM provides architectural context for business concepts:

"metadata": {
  "semanticCoreLink": "dsl://sales/OrderPolicy",
  "implementsRules": [
    "order-minimum-value-rule",
    "customer-credit-check-rule"
  ]
}

Linkage:

CALM service → implements SBVR Policy
CALM relationship → realizes SBVR Flow
CALM nodes → map to DDD Bounded Contexts

7.2. SEA™ Core (Cognitive & Governance)

Cognitive Layer:

AI agents query CALM model to understand system structure
Context Analyzer uses CALM for architectural awareness
Artifact generation respects architectural constraints

Governance Layer:

CALM CLI validates architectural compliance
Controls mapped to NIST/ISO frameworks
Real-time drift detection

7.3. VibesPro™ (App Generator)

CALM serves as blueprint for code generation:

# Input: CALM definition
nodes:
  - id: user-service
    type: service
    metadata:
      language: Python
      framework: FastAPI

# Output: Generated FastAPI project structure
user-service/
  ├── src/
  │   ├── main.py          # FastAPI app
  │   ├── models/
  │   └── routers/
  ├── tests/
  └── Dockerfile

Generation Capabilities:

Service scaffolding (FastAPI, Express, etc.)
API interface definitions (OpenAPI specs)
Infrastructure-as-Code (Terraform, K8s)
Database schemas (SQL DDL, Prisma)

7.4. Knowledge Layer (Oxigraph)

CALM model transformed into graph representation:

// Nodes become Oxigraph nodes
CREATE (order:Service {id: 'order-service', name: 'Order Processing'})
CREATE (db:Database {id: 'customer-db', type: 'PostgreSQL'})

// Relationships become edges
CREATE (order)-[:READS_WRITES {protocol: 'JDBC'}]->(db)

Query Capabilities:

Dependency analysis
Impact assessment
Architectural pattern detection
Semantic queries (Cypher)

7.5. GovernedSpeed™ (Runtime Governance)

CALM controls enforced at runtime:

"controls": [
  {
    "id": "rate-limit-100-rps",
    "description": "Maximum 100 requests/second",
    "status": "compliant"
  }
]

Runtime Enforcement:

API Gateway (Kong) enforces rate limits
Service mesh applies encryption policies
Observability monitors compliance status

8. FINOS CALM CLI Tooling

8.1. `calm validate`

Validates architecture against schema and controls:

calm validate architecture/payment.calm.json

Checks:

✅ JSON schema validity
✅ Node/relationship integrity
✅ Control compliance
✅ Architectural patterns
✅ Custom rules

CI/CD Integration:

# .github/workflows/architecture-governance.yml
- name: Validate Architecture
  run: calm validate architecture/*.calm.json

8.2. `calm docify`

Generates documentation from CALM model:

calm docify architecture/ --output docs/architecture/

Outputs:

Markdown documentation
Docusaurus site
C4 diagrams
Compliance reports

Benefits:

Always in sync with architecture
No manual documentation drift
Searchable, hyperlinked

8.3. `calm generate`

Scaffolds architecture files from templates:

calm generate --pattern microservice --name payment-service

Patterns:

Microservice (API + DB)
Event-driven (Producer + Queue + Consumer)
Batch processing (Scheduler + Worker + Storage)

8.4. CALM Hub (UI)

Web-based visualization tool:

Features:

Interactive architecture diagrams
Control status dashboard
Dependency graph explorer
Change impact analysis

URL: https://github.com/finos/architecture-as-code/tree/main/calm-hub

9. SEA-Forge™ Implementation Guide

9.1. File Organization

architecture/
  ├── core/
  │   ├── semantic-core.calm.json       # DomainForge™ services
  │   ├── cognitive-extension.calm.json # SEA™ Core cognitive services
  │   └── governance.calm.json          # GovernedSpeed™ controls
  ├── generated/
  │   └── vibes-pro.calm.json          # Generated apps
  └── external/
      └── integrations.calm.json       # Third-party APIs

9.2. Validation Pipeline

Pre-commit Hook:

#!/bin/bash
calm validate architecture/**/*.calm.json || exit 1

CI Pipeline:

test:
  script:
    - calm validate architecture/
    - calm docify --check-only # Ensure docs can be generated

9.3. Custom Controls for SEA-Forge™

"controls": [
  {
    "id": "semantic-core-linkage",
    "description": "Service must link to DomainForge™ definition",
    "status": "compliant"
  },
  {
    "id": "ai-agent-grounding",
    "description": "AI agents must operate within CALM-defined boundaries",
    "status": "compliant"
  },
  {
    "id": "hexagonal-architecture",
    "description": "Services must follow hexagonal architecture pattern",
    "status": "compliant"
  }
]

9.4. SEA-Forge™ Node Type Extensions

{
  "id": "artifact-recommendation-agent",
  "type": "ai-agent",
  "metadata": {
    "baseModel": "GPT-4",
    "contextSources": ["knowledge-graph", "user-conversation"],
    "governedBy": "sea-core-governance"
  }
}

10. Best Practices

10.1. Naming Conventions

Node IDs: kebab-case (e.g., order-processing-service)
Relationship IDs: source-to-target (e.g., order-to-payment-gateway)
Control IDs: domain-requirement (e.g., pci-dss-encryption)

10.2. Metadata Strategy

Start Minimal:

"metadata": {
  "team": "Alpha Squad",
  "language": "Python"
}

Grow as Needed:

"metadata": {
  "team": "Alpha Squad",
  "language": "Python",
  "deployment": "Kubernetes",
  "semanticCoreLink": "dsl://sales/Order",
  "sla": "99.9%",
  "oncall": "alpha@company.com"
}

10.3. Version Control

# Tag architecture versions
git tag -a arch-v1.0.0 -m "Initial e-commerce architecture"

# Branch for experimental designs
git checkout -b feat/add-recommendation-engine
# Update architecture/*.calm.json
calm validate architecture/

10.4. Control Management

Centralize Control Definitions:

// controls/security.json
{
  "controls": [
    { "id": "encryption-at-rest", "framework": "NIST CSF" },
    { "id": "least-privilege", "framework": "ISO 27001" }
  ]
}

Reference in CALM:

"controls": [
  {"$ref": "controls/security.json#encryption-at-rest", "status": "compliant"}
]

SDS-001: Data Model Schemas - CALM JSON schema implementation
ANALYSIS-001: SEA™ Original Domain Analysis - Architectural Governance domain
ARCH-001: SEA™ Container Diagram - CALM CLI Service
ADR-001: Core Principles - “Architecture Must Be Enforceable”

12. References

FINOS CALM GitHub: https://github.com/finos/architecture-as-code
CALM Specification: https://github.com/finos/architecture-as-code/tree/main/calm
CALM CLI Documentation: https://github.com/finos/architecture-as-code/tree/main/cli
CALM Hub: https://github.com/finos/architecture-as-code/tree/main/calm-hub

Status: This specification defines CALM DSL usage for SEA-Forge™ Architectural Governance. Implementation should follow FINOS CALM standard with SEA-specific extensions.