Timeline Support in Docify/VSCode Tooling - v1.2

[LeighFinegold]

Background

Docify

Docify is a CLI command (calm docify) that generates documentation websites from CALM architecture files. It loads a CALM JSON file, parses it into typed models, transforms to canonical format, and renders HTML via Handlebars templates with embedded widgets - outputting static HTML/Markdown suitable for Docusaurus or standalone viewing.

Widget Framework

@finos/calm-widgets provides reusable Handlebars-based visualization components (tables, sequence diagrams, block diagrams, etc.) that transform CALM canonical model data into HTML. Widgets are registered as Handlebars helpers and used in both CLI docify output and VSCode preview rendering.

VSCode Extension

The VSCode plugin provides live, in-IDE interaction with CALM architectures - allowing developers to browse, visualize, and validate their architecture models without leaving their editor.

TreeView (Navigation)

• Sidebar showing architecture structure (nodes, relationships, flows)
• Click to navigate between components

Preview Panel (Visualization)

• Visual rendering of architecture using the same widget pipeline as docify
• What you see in the IDE matches what gets generated as documentation

Key Principle: TreeView handles navigation, Preview handles visualization via widgets. This ensures consistent rendering across VSCode and CLI docify output.

---

Description of Feature

Add comprehensive timeline visualization and navigation support to CALM tooling, enabling users to:

• Visualize architecture evolution over time
• Navigate between architecture versions at different milestones
• Generate documentation showing the complete architecture roadmap

CALM 1.2 already defines timeline.json and calm-timeline.json schemas, and calm-models has corresponding TypeScript types. However, the tooling cannot currently visualize or navigate timeline documents.

Not In Scope

Currently the below doesn't cover calm-hub-ui but we can adapt the issue according or raised an additional issue for that support.

---

User Stories

US1: Timeline Visualization

As an user,
I want to see a visual timeline of my architecture evolution,
So that I can understand and communicate how the system changes over time.

Proposed Implementation:

• New timeline-widget in calm-widgets renders a visual timeline with milestones
• Each milestone displays as a clickable link pointing to its architecture-ref URL
• Clicking a milestone navigates to the architecture (can be opened inline, in iframe, or new tab depending on context)
• Widget usable in templates via: {{timeline timelineData}}
• Works in both VSCode preview and CLI docify output (same widget, consistent rendering)

---

US2: Milestone Navigation

As a user,
I want to click on a timeline milestone and see that version of the architecture,
So that I can quickly compare different points in the architecture's evolution.

Proposed Implementation:

• Timeline widget renders clickable milestone markers
• Clicking opens the referenced architecture file
• Uses existing NavigationService with URL mapping for resolution

---

US3: TreeView Timeline Support

As a user,
I want to see timeline milestones in the sidebar when I open a timeline file,
So that I can navigate between architecture versions without manually opening files.

Proposed Implementation:

• Detect timeline files via $schema field
• TreeView displays milestones as expandable nodes:

📅 Architecture Timeline: {name}
├── 📍 {milestone-1-name} ({date})
│   └── 🔗 {architecture-file}
├── 📍 {milestone-2-name} ({date})
│   └── 🔗 {architecture-file}
└── 📍 {milestone-3-name} ({date})
    └── 🔗 {architecture-file}

• Clicking milestone opens referenced architecture in the current editor/preview view
• Preview panel updates to show the selected architecture visualization

---

US4: Milestone Comparison

As a user,
I want to compare two milestones side-by-side,
So that I can understand what changed between architecture versions.

Proposed Implementation:

• Select two milestones to compare
• Side-by-side diff view showing:
  • Nodes added/removed/modified
  • Relationships changed
  • Visual diff of block diagrams
• Could leverage existing diff tooling or build custom comparison widget

---

Current Limitations

Component	Current State	Gap
CALM 1.2 Spec	timeline.json schema exists	✅ No gap
calm-models	timeline-types.ts exists	✅ No gap
calm-widgets	6 widgets, none for timelines	❌ No timeline-widget
shared/docify	Single architecture only	❌ No timeline template
CLI docify	calm docify -a arch.json	❌ Cannot process timeline.json
VSCode TreeView	Shows nodes/relationships/flows	❌ No timeline milestone display
VSCode Preview	Renders via widgets	❌ No timeline visualization

Summary: The schema and types exist, but visualization, navigation, and documentation generation are missing.

---

Proposed Implementation Phases

Phase 1: Timeline Widget (calm-widgets)

• New timeline-widget renders visual timeline with milestones
• Template uses Mermaid or HTML/CSS for visualization
• Usage: {{timeline timelineData}}

Phase 2: Timeline Template Bundle (shared)

• New timeline template for docusaurus bundle
• Generates timeline overview page with embedded widget
• Links to architecture documentation for each milestone

Phase 3: VSCode TreeView Enhancement (calm-plugins/vscode)

• Detect timeline files via $schema field
• Display milestones as navigable tree nodes
• Clicking milestone opens referenced architecture via existing NavigationService
• Preview panel shows timeline-widget visualization

Phase 4: Multi-Architecture Docify (cli/shared)

• Enhanced docify to process timeline.json
• Generates documentation for all referenced architectures
• Output structure with timeline index and milestone subdirectories

Phase 5: Diffing Architecture?

---

Additional Context

Timeline Schema Structure (CALM 1.2)

{
  "$schema": "https://calm.finos.org/release/1.2/meta/calm-timeline.json",
  "name": "Architecture Evolution",
  "description": "Evolution from insecure to secure architecture",
  "milestones": [
    {
      "unique-id": "initial",
      "name": "Initial State",
      "date": "2024-Q1",
      "description": "Starting architecture without security controls",
      "architecture-ref": "https://example.com/arch-insecure.json"
    },
    {
      "unique-id": "secured",
      "name": "Fully Secured",
      "date": "2024-Q3",
      "description": "Architecture with all security controls implemented",
      "architecture-ref": "https://example.com/arch-secure.json"
    }
  ]
}

[LeighFinegold]

The issue was discussed as part of 5th Feb Office Hours (#2090 ) and concluded we would just implement User Story 3 for now.

Attaching a POC for comment

TimelineVsCodeSupport.mov