Skip to content

Add CALM Architecture artifacts for TraderX#333

Open
jimthompson5802 wants to merge 16 commits into
finos:mainfrom
jimthompson5802:iss-331-add-calm-architecture-artifacts
Open

Add CALM Architecture artifacts for TraderX#333
jimthompson5802 wants to merge 16 commits into
finos:mainfrom
jimthompson5802:iss-331-add-calm-architecture-artifacts

Conversation

@jimthompson5802

@jimthompson5802 jimthompson5802 commented Mar 29, 2026

Copy link
Copy Markdown

Add CALM Architecture Documentation for TraderX

Close #331

Overview

This PR introduces a comprehensive CALM (Common Architecture Language Model) architecture definition for the TraderX trading system, providing a machine-readable, validated architecture model alongside auto-generated documentation.

What is CALM?

CALM is a FINOS sibling project that provides a JSON-based declarative language for describing system architectures. It enables machine-readable architecture definitions, automated validation, compliance tracking, and integration with governance tools.

Changes

New Files Added

  • trading-system.architecture.json (987 lines) - Complete CALM architecture model covering all TraderX services, interfaces, relationships, and business flows
  • README.md - Comprehensive guide explaining CALM, how to view the architecture, and how to generate documentation
  • trading-system-overview.md (879 lines) - Auto-generated system architecture overview
  • flow-overview.md (137 lines) - Auto-generated business flow diagrams and descriptions
  • templates - Handlebars templates for generating documentation from the CALM model
    • architecture-overview.md.hbs
    • flows-overview.md.hbs
  • calm-vscode-tool-box.png - Screenshot showing VSCode extension integration
  • .gitignore - Not sure how much TraderX wanted to be align with a particular coding agent. So I excluded the Github Copilot CALM prompts.

Architecture Coverage

The CALM model includes:

  • 9+ nodes covering all major services (Trading Services, Account Service, Position Service, People Service, Reference Data Service, Trade Processor, Database, Trade Feed, Web GUI)
  • Actor definitions (Trader)
  • REST API interfaces for each service
  • 7 business flows (Load List of Accounts, Bootstrap Trade and Position Blotter, Submit Trade Ticket, Process Trade Event, Add or Update Account, Add or Update Users to Account, Reference Data Service Bootstrap)

Implementation notes

Original intent was to create CALM architecture that is equivalent to the information found in docs/c4/workspace.dsl (CALM nodes and relationships) and docs/flows.md (CALM flows). After creating the CALM nodes, relationships and flows, calm validation identified the flow Reference Data Service Bootstrap referenced a CSV file that was not defined as a CALM node.

I confirmed the inconsistency between workspace.dsl (missing reference to csv file) and flows.md and there is code reference-data/src/data-loader/load-csv-data.ts to load a CSV file for S&P 500 related information. As a result I added a CSV file node to the CALM architecture.
image

Other than this one difference the CALM architecture should match the existing workspace.dsl and flows.md content.

@netlify

netlify Bot commented Mar 29, 2026

Copy link
Copy Markdown

Deploy Preview for lucky-concha-f3599f canceled.

Name Link
🔨 Latest commit d6f4070
🔍 Latest deploy log https://app.netlify.com/projects/lucky-concha-f3599f/deploys/69c9d4284ff89d00088be2b5

@jimthompson5802 jimthompson5802 marked this pull request as ready for review March 29, 2026 20:59
@jimthompson5802

Copy link
Copy Markdown
Author

@DovOps ready for review.

@DovOps

DovOps commented Mar 30, 2026

Copy link
Copy Markdown
Collaborator

Thanks. Take a look at this comment so you can understand a bit more about the context of the discussion on Friday during the meeting.

#332 (comment)

I will look and review this after hours. Thanks again for your contribution.

@DovOps DovOps added the V1-Do-Not-Merge We are doing a major refactor of TraderX. We need to reconsider all existing PRs label May 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

V1-Do-Not-Merge We are doing a major refactor of TraderX. We need to reconsider all existing PRs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add CALM Architecture documentation for TraderX

2 participants