|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Install dependencies |
| 13 | +npm i |
| 14 | + |
| 15 | +# Start development server (runs on http://[::]:8080) |
| 16 | +npm run dev |
| 17 | + |
| 18 | +# Build for production |
| 19 | +npm run build |
| 20 | + |
| 21 | +# Build in development mode |
| 22 | +npm run build:dev |
| 23 | + |
| 24 | +# Lint code |
| 25 | +npm run lint |
| 26 | + |
| 27 | +# Preview production build |
| 28 | +npm run preview |
| 29 | +``` |
| 30 | + |
| 31 | +## Architecture |
| 32 | + |
| 33 | +### Core Application Flow |
| 34 | + |
| 35 | +1. **App.tsx**: Root component that sets up routing, React Query, and toast providers |
| 36 | +2. **pages/Index.tsx**: Main page that orchestrates the three-panel layout using ResizablePanelGroup |
| 37 | +3. **State Management**: Simple React state in Index.tsx manages: |
| 38 | + - `jsonContent`: Raw JSON string for the editor |
| 39 | + - `parsedData`: Parsed CALM object for visualization |
| 40 | + - `selectedNode`: Currently selected node for details view |
| 41 | + |
| 42 | +### Key Components |
| 43 | + |
| 44 | +**JsonEditor** (`components/JsonEditor.tsx`) |
| 45 | +- Monaco editor for JSON input |
| 46 | +- File upload functionality |
| 47 | +- Validates and parses JSON on change |
| 48 | + |
| 49 | +**ArchitectureGraph** (`components/ArchitectureGraph.tsx`) |
| 50 | +- Uses ReactFlow for graph visualization |
| 51 | +- Dagre algorithm for automatic layout (left-to-right, configurable spacing) |
| 52 | +- Parses FINOS CALM format with nested `relationship-type.connects` structure |
| 53 | +- Handles both array and object node formats |
| 54 | +- Custom edge rendering with protocol tooltips |
| 55 | + |
| 56 | +**NodeDetails** (`components/NodeDetails.tsx`) |
| 57 | +- Displays selected node properties |
| 58 | +- Replaces graph view when a node is clicked |
| 59 | + |
| 60 | +**CustomEdge** (`components/CustomEdge.tsx`) |
| 61 | +- Custom ReactFlow edge with hover tooltips |
| 62 | +- Shows description and protocol information |
| 63 | +- Uses EdgeLabelRenderer for proper z-index handling |
| 64 | + |
| 65 | +### FINOS CALM Data Structure |
| 66 | + |
| 67 | +The app expects CALM JSON with this structure: |
| 68 | + |
| 69 | +```json |
| 70 | +{ |
| 71 | + "nodes": [ |
| 72 | + { |
| 73 | + "unique-id": "node-id", |
| 74 | + "name": "Node Name", |
| 75 | + "node-type": "system|service|data-store", |
| 76 | + "interfaces": [...] |
| 77 | + } |
| 78 | + ], |
| 79 | + "relationships": [ |
| 80 | + { |
| 81 | + "unique-id": "rel-id", |
| 82 | + "relationship-type": { |
| 83 | + "connects": { |
| 84 | + "source": { "node": "source-id", "interface": "interface-id" }, |
| 85 | + "destination": { "node": "dest-id", "interface": "interface-id" } |
| 86 | + } |
| 87 | + }, |
| 88 | + "protocol": "HTTPS|MCP|..." |
| 89 | + } |
| 90 | + ] |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +### Layout Algorithm |
| 95 | + |
| 96 | +Graph layout uses Dagre with these settings: |
| 97 | +- `rankdir: 'LR'` (left to right) |
| 98 | +- `ranksep: 150` (horizontal spacing between ranks) |
| 99 | +- `nodesep: 100` (vertical spacing between nodes) |
| 100 | +- Node dimensions: 250x100 |
| 101 | + |
| 102 | +To modify layout, adjust parameters in `getLayoutedElements()` in ArchitectureGraph.tsx. |
| 103 | + |
| 104 | +### Styling System |
| 105 | + |
| 106 | +- **Framework**: Tailwind CSS with shadcn/ui components |
| 107 | +- **Theme**: HSL-based CSS variables for colors (supports dark mode via `class` strategy) |
| 108 | +- **Component library**: Full shadcn/ui suite in `components/ui/` |
| 109 | +- **Path alias**: `@/` maps to `src/` |
| 110 | + |
| 111 | +### State and Data Flow |
| 112 | + |
| 113 | +1. User inputs JSON in JsonEditor or uploads file |
| 114 | +2. onChange handler in Index.tsx updates `jsonContent` and attempts parse |
| 115 | +3. Valid JSON updates `parsedData` state |
| 116 | +4. ArchitectureGraph receives `parsedData` and re-renders graph |
| 117 | +5. Clicking a node calls `onNodeClick` which updates `selectedNode` |
| 118 | +6. NodeDetails panel replaces graph when `selectedNode` is set |
| 119 | + |
| 120 | +## Git Commit Requirements |
| 121 | + |
| 122 | +**CRITICAL**: This repository has CLA (Contributor License Agreement) checks that require commits to be authored by @pmerrison. |
| 123 | + |
| 124 | +- Git is already configured correctly with author: Paul Merrison <paul@tetrate.io> |
| 125 | +- **DO NOT** modify git author configuration |
| 126 | +- **DO NOT** use any other author name or email in commits |
| 127 | +- All commits must pass CLA checks to be accepted into the upstream repository |
| 128 | + |
| 129 | +When creating commits, the configured git author will automatically be used. No additional action is required. |
| 130 | + |
| 131 | +## Project Configuration |
| 132 | + |
| 133 | +- **Vite**: SWC-based React plugin for fast builds |
| 134 | +- **TypeScript**: Strict mode enabled |
| 135 | +- **Dev Server**: Runs on port 8080, listens on all interfaces (`::`), configured in vite.config.ts |
| 136 | +- **ESLint**: React hooks and refresh plugins configured |
| 137 | +- **Build Tool**: Vite with production optimizations |
0 commit comments