feat(calm-explorer): add interactive CALM architecture explorer

.github/workflows/build-calm-explorer.yml

@@ -0,0 +1,38 @@
+name: Build CALM Explorer
+
+permissions:
+    contents: read
+
+on:
+    pull_request:
+        branches:
+            - 'main'
+    push:
+        branches:
+            - 'main'
+
+jobs:
+    calm-explorer:
+        name: Build, Test, and Lint CALM Explorer
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout PR Branch
+              uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+
+            - name: Setup Node.js
+              uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+              with:
+                  node-version: v22
+
+            - name: Install workspace
+              run: npm ci
+
+            - name: Lint Module
+              run: npm run lint --workspace=experimental/calm-explorer
+
+            - name: Build workspace
+              run: npm run build --workspace=experimental/calm-explorer
+
+            - name: Run tests
+              run: npm run test:run --workspace=experimental/calm-explorer

.gitignore

@@ -11,8 +11,8 @@ website/node_modules/
 # Generated docs
 docs/contributing.md
 
-# We use YARN
-website/package-lock.json
+# We use YARN (but also need package-lock.json for CI)
+# website/package-lock.json
 /.idea/
 
 **/.vscode/

experimental/calm-explorer/.gitignore

@@ -0,0 +1,26 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+docs
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+pbcopy

experimental/calm-explorer/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a React-based visualization tool for FINOS CALM (Common Architecture Language Model) architecture diagrams. It provides an interactive graph visualization with a JSON editor, allowing users to visualize and explore software architecture definitions.
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm i
+
+# Start development server (runs on http://[::]:8080)
+npm run dev
+
+# Build for production
+npm run build
+
+# Build in development mode
+npm run build:dev
+
+# Lint code
+npm run lint
+
+# Preview production build
+npm run preview
+```
+
+## Architecture
+
+### Core Application Flow
+
+1. **App.tsx**: Root component that sets up routing, React Query, and toast providers
+2. **pages/Index.tsx**: Main page that orchestrates the three-panel layout using ResizablePanelGroup
+3. **State Management**: Simple React state in Index.tsx manages:
+   - `jsonContent`: Raw JSON string for the editor
+   - `parsedData`: Parsed CALM object for visualization
+   - `selectedNode`: Currently selected node for details view
+
+### Key Components
+
+**JsonEditor** (`components/JsonEditor.tsx`)
+- Monaco editor for JSON input
+- File upload functionality
+- Validates and parses JSON on change
+
+**ArchitectureGraph** (`components/ArchitectureGraph.tsx`)
+- Uses ReactFlow for graph visualization
+- Dagre algorithm for automatic layout (left-to-right, configurable spacing)
+- Parses FINOS CALM format with nested `relationship-type.connects` structure
+- Handles both array and object node formats
+- Custom edge rendering with protocol tooltips
+
+**NodeDetails** (`components/NodeDetails.tsx`)
+- Displays selected node properties
+- Replaces graph view when a node is clicked
+
+**CustomEdge** (`components/CustomEdge.tsx`)
+- Custom ReactFlow edge with hover tooltips
+- Shows description and protocol information
+- Uses EdgeLabelRenderer for proper z-index handling
+
+### FINOS CALM Data Structure
+
+The app expects CALM JSON with this structure:
+
+```json
+{
+  "nodes": [
+    {
+      "unique-id": "node-id",
+      "name": "Node Name",
+      "node-type": "system|service|data-store",
+      "interfaces": [...]
+    }
+  ],
+  "relationships": [
+    {
+      "unique-id": "rel-id",
+      "relationship-type": {
+        "connects": {
+          "source": { "node": "source-id", "interface": "interface-id" },
+          "destination": { "node": "dest-id", "interface": "interface-id" }
+        }
+      },
+      "protocol": "HTTPS|MCP|..."
+    }
+  ]
+}
+```
+
+### Layout Algorithm
+
+Graph layout uses Dagre with these settings:
+- `rankdir: 'LR'` (left to right)
+- `ranksep: 150` (horizontal spacing between ranks)
+- `nodesep: 100` (vertical spacing between nodes)
+- Node dimensions: 250x100
+
+To modify layout, adjust parameters in `getLayoutedElements()` in ArchitectureGraph.tsx.
+
+### Styling System
+
+- **Framework**: Tailwind CSS with shadcn/ui components
+- **Theme**: HSL-based CSS variables for colors (supports dark mode via `class` strategy)
+- **Component library**: Full shadcn/ui suite in `components/ui/`
+- **Path alias**: `@/` maps to `src/`
+
+### State and Data Flow
+
+1. User inputs JSON in JsonEditor or uploads file
+2. onChange handler in Index.tsx updates `jsonContent` and attempts parse
+3. Valid JSON updates `parsedData` state
+4. ArchitectureGraph receives `parsedData` and re-renders graph
+5. Clicking a node calls `onNodeClick` which updates `selectedNode`
+6. NodeDetails panel replaces graph when `selectedNode` is set
+
+## Git Commit Requirements
+
+**CRITICAL**: This repository has CLA (Contributor License Agreement) checks that require commits to be authored by @pmerrison.
+
+- Git is already configured correctly with author: Paul Merrison <paul@tetrate.io>
+- **DO NOT** modify git author configuration
+- **DO NOT** use any other author name or email in commits
+- All commits must pass CLA checks to be accepted into the upstream repository
+
+When creating commits, the configured git author will automatically be used. No additional action is required.
+
+## Project Configuration
+
+- **Vite**: SWC-based React plugin for fast builds
+- **TypeScript**: Strict mode enabled
+- **Dev Server**: Runs on port 8080, listens on all interfaces (`::`), configured in vite.config.ts
+- **ESLint**: React hooks and refresh plugins configured
+- **Build Tool**: Vite with production optimizations