CALM Integration Plan — Continuous Architecture Platform¶

                    CALM Topology Layer (NEW)
                    ├── Nodes (services, DBs, actors, apps)
                    ├── Relationships (REST, events, DB connections)
                    ├── Interfaces (endpoints, Kafka channels, JDBC)
                    └── Controls (PCI, auth, data ownership)
                         │
        ┌────────────────┼────────────────┐
        │                │                │
  OpenAPI Specs    AsyncAPI Specs    Solution Designs
  (API contracts)  (Event schemas)   (Change lifecycle)
        │                │                │
        └────────────────┼────────────────┘
                         │
                  Portal Generators
                  (merge topology + contracts + solutions → pages)

architecture/
├── calm/
│   ├── novatrek-system.json          (Phase 1 — full system)
│   ├── domains/
│   │   └── operations.json           (Phase 0 — pilot domain)
│   ├── patterns/
│   │   ├── novatrek-microservice.json
│   │   ├── novatrek-event-driven.json
│   │   └── novatrek-3tier.json
│   ├── controls/
│   │   ├── data-ownership.json
│   │   ├── pci-scope.json
│   │   └── api-mediated-access.json
│   └── standards/
│       └── novatrek-org-standard.json
├── metadata/                          (existing — unchanged during Phase 0)
├── specs/                             (existing — unchanged)
└── events/                            (existing — unchanged)

# portal/mkdocs.yml (new nav entry)
nav:
  - Topology:
    - System Map: topology/system-map.md
    - Dependency Matrix: topology/dependency-matrix.md
    - Data Flows: topology/data-flows/index.md
    - PCI Scope: topology/pci-scope.md

# capability-changelog.yaml entry
entries:
  - ticket: NTK-10010
    date: 2026-04-01
    solution: _NTK-10010-real-time-adventure-tracking
    summary: Add real-time GPS tracking for active adventures
    capabilities:
      - id: CAP-2.4
        impact: new
        description: Real-time location tracking during adventures
    topology_changes:
      nodes_added:
        - id: svc-location-tracking
          type: service
          domain: Operations
      relationships_added:
        - source: svc-check-in
          target: svc-location-tracking
          type: interacts
          protocol: HTTPS
        - source: svc-location-tracking
          target: kafka-broker
          type: interacts
          protocol: Kafka
          channel: novatrek.operations.location.updated
      interfaces_added:
        - node: svc-location-tracking
          type: path
          path: /adventures/{id}/location

# Install globally
npm install -g @finos/calm-cli

# Verify
calm --version

# .github/workflows/validate-solution.yml (addition)
  calm-validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @finos/calm-cli
      - name: Validate CALM topology
        run: |
          for domain in architecture/calm/domains/*.json; do
            calm validate \
              -p architecture/calm/patterns/novatrek-microservice.json \
              -a "$domain" \
              -f junit \
              -o "test-results/calm-$(basename $domain .json).xml"
          done
      - name: Validate system composition
        run: |
          calm validate \
            -a architecture/calm/novatrek-system.json \
            --strict \
            -f junit \
            -o test-results/calm-system.xml
      - name: Publish CALM results
        uses: dorny/test-reporter@v1
        if: always()
        with:
          name: CALM Validation
          path: test-results/calm-*.xml
          reporter: java-junit

Architect edits YAML (existing workflow)
  → Bridge script generates CALM from YAML
  → calm validate checks CALM documents
  → Any validation failure = CI red

OR

Architect edits CALM (new workflow)
  → Bridge script generates YAML from CALM
  → Existing generators read YAML as before
  → calm validate checks CALM documents

{
  "unique-id": "svc-check-in",
  "node-type": "service",
  "name": "Check-In Service",
  "description": "Manages day-of-adventure check-in workflows including identity verification, waiver validation, and equipment assignment",
  "interfaces": [
    {
      "unique-id": "svc-check-in-api",
      "type": "path",
      "path": "/check-ins"
    },
    {
      "unique-id": "svc-check-in-event-completed",
      "type": "path",
      "path": "novatrek.operations.checkin.completed"
    }
  ],
  "metadata": {
    "domain": "Operations",
    "team": "NovaTrek Operations Team",
    "data-classification": "internal",
    "pci-in-scope": false
  }
}

{
  "unique-id": "db-check-in",
  "node-type": "database",
  "name": "Check-In Database",
  "description": "PostgreSQL database storing check-in records, session data, and equipment assignments",
  "interfaces": [
    {
      "unique-id": "db-check-in-jdbc",
      "type": "host-port",
      "host": "checkin-db.novatrek.internal",
      "port": 5432
    }
  ],
  "metadata": {
    "engine": "PostgreSQL 15",
    "schema": "checkin",
    "tables": ["check_ins", "equipment_assignments", "waiver_validations"]
  }
}

{
  "unique-id": "rel-checkin-to-reservations",
  "relationship-type": "interacts",
  "description": "Check-in service retrieves reservation details for guest verification",
  "protocol": "HTTPS",
  "source": {
    "node": "svc-check-in"
  },
  "destination": {
    "node": "svc-reservations",
    "interface": "svc-reservations-api"
  }
}

{
  "unique-id": "rel-checkin-event-completed",
  "relationship-type": "interacts",
  "description": "Check-in service publishes completion event consumed by analytics and notifications",
  "protocol": "Kafka",
  "source": {
    "node": "svc-check-in",
    "interface": "svc-check-in-event-completed"
  },
  "destination": {
    "node": "kafka-broker",
    "interface": "kafka-checkin-completed-topic"
  }
}

{
  "$schema": "https://calm.finos.org/release/1.2/meta/calm.json",
  "title": "NovaTrek Microservice Pattern",
  "description": "Every NovaTrek microservice must have exactly one owned database, expose an HTTPS API, and declare a team owner",
  "type": "object",
  "properties": {
    "nodes": {
      "type": "array",
      "prefixItems": [
        {
          "properties": {
            "node-type": { "const": "service" },
            "interfaces": {
              "type": "array",
              "minItems": 1
            },
            "metadata": {
              "type": "object",
              "required": ["domain", "team", "data-classification"]
            }
          },
          "required": ["unique-id", "node-type", "name", "interfaces", "metadata"]
        },
        {
          "properties": {
            "node-type": { "const": "database" }
          },
          "required": ["unique-id", "node-type", "name"]
        }
      ],
      "minItems": 2,
      "maxItems": 2
    },
    "relationships": {
      "type": "array",
      "minItems": 1,
      "items": {
        "properties": {
          "relationship-type": { "enum": ["connects", "interacts"] },
          "protocol": { "type": "string" }
        },
        "required": ["unique-id", "relationship-type", "protocol"]
      }
    }
  },
  "required": ["nodes", "relationships"]
}

{
  "$schema": "https://calm.finos.org/release/1.2/meta/control-requirement.json",
  "unique-id": "ctrl-data-ownership",
  "name": "Exclusive Data Ownership",
  "description": "Each database node must be connected to exactly one service node. No shared databases between services.",
  "control-requirement-url": "https://architecture.novatrek.example.com/standards/data-ownership",
  "severity": "error"
}

Ticket Assigned
  |
  v
Create Branch: solution/NTK-XXXXX-slug
  |
  v
Run Prior-Art Discovery (EXISTING)
  |
  v
Create Solution in architecture/solutions/_NTK-XXXXX-slug/
  |-- (existing folders unchanged)
  |-- 3.solution/
  |   |-- t.topology/                    ← NEW
  |   |   |-- topology-changes.json      ← CALM diff fragment
  |   |   |-- topology-changes.md        ← Human-readable summary
  |
  v
Update Metadata (EXISTING + NEW):
  |-- architecture/metadata/capabilities.yaml (existing)
  |-- architecture/metadata/capability-changelog.yaml (existing, with topology_changes)
  |-- architecture/calm/domains/{domain}.json  ← NEW: topology changes
  |
  v
Open Pull Request
  |-- CI validates YAML (existing)
  |-- CI validates CALM topology (NEW)
  |-- CI runs calm validate against patterns and controls (NEW)
  |-- Reviewer applies architecture checklist (existing)
  |
  v
Merge to Main → Portal Publishes → Topology Updates → Architecture Grows

Phase 0-1 (Parallel):
  YAML files → existing generators → portal pages
  CALM files → calm validate → CI check (governance only)

Phase 2+ (Integrated):
  CALM files → topology generators → topology pages, data flow diagrams
  CALM files → bridge → YAML → existing generators → service pages
  (or)
  CALM files → updated generators → service pages (direct consumption)