# cameronsjo/spec-compare architecture

> Architecture diagram of the GitHub repository cameronsjo/spec-compare, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cameronsjo/spec-compare
- Repository: https://github.com/cameronsjo/spec-compare

## Overview

This repository is an independent research comparison of spec-driven development tools, presented through an interactive site. The user-facing path starts at the site shell, which selects a workflow comparison, individual tool profile, feature matrix, scoring heatmap, or decision guide; these views derive their content from tool JSON and research-derived types and scoring logic. README documents the broader research capabilities, including worktree analysis and orchestration landscape, but those live in documentation rather than sampled runtime modules. Edges below follow explicit imports and calls; documentation-only branches are linked only where the README names the capability.

Main entry points: [`site/src/App.tsx`](https://github.com/cameronsjo/spec-compare/blob/main/site/src/App.tsx) (Application shell), [`site/src/data.ts`](https://github.com/cameronsjo/spec-compare/blob/main/site/src/data.ts) (Tool specifications), [`site/src/WorkflowCompare.tsx`](https://github.com/cameronsjo/spec-compare/blob/main/site/src/WorkflowCompare.tsx) (Workflow comparison), [`site/src/WorkflowPlayer.tsx`](https://github.com/cameronsjo/spec-compare/blob/main/site/src/WorkflowPlayer.tsx) (Workflow player)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Interactive site"]
  node_app["Application shell<br/>[App.tsx]"]
  node_workflow_compare["Workflow comparison"]
  node_workflow_player["Workflow player<br/>[WorkflowPlayer.tsx]"]
  node_loop_graph["Workflow graph<br/>[LoopGraph.tsx]"]
  node_controls["Playback controls<br/>[controls.tsx]"]
  node_player_logic["Playback state<br/>[player.ts]"]
  node_feature_matrix["Feature matrix<br/>[FeatureMatrix.tsx]"]
  node_heatmap["Scoring heatmap<br/>[ScoringHeatmap.tsx]"]
  node_tool_profile["Tool profiles<br/>[ToolProfile.tsx]"]
  node_decision_guide["Decision guide<br/>[DecisionGuide.tsx]"]
  node_about["About and disclosure<br/>[About.tsx]"]
  node_score_pip["Score indicator<br/>[ScorePip.tsx]"]
  node_anchored_text["Emphasized text<br/>[Anchored.tsx]"]
end

subgraph group_data["Comparison data"]
  node_tool_data["Tool specifications<br/>[data.ts]"]
  node_tool_json["Tool data files"]
  node_domain_types["Comparison model<br/>[types.ts]"]
  node_score_logic["Score formatting<br/>[score.ts]"]
end

subgraph group_research["Research library"]
  node_research_docs["Research and analysis"]
  node_worktree_research["Worktree analysis"]
  node_orchestration_research["Orchestration landscape<br/>[landscape.md]"]
end

node_visitor(("Site visitor"))

node_visitor -->|"opens"| node_app
node_app -->|"routes to"| node_workflow_compare
node_app -->|"routes to"| node_workflow_player
node_app -->|"routes to"| node_feature_matrix
node_app -->|"routes to"| node_heatmap
node_app -->|"routes to"| node_tool_profile
node_app -->|"routes to"| node_decision_guide
node_app -->|"routes to"| node_about
node_tool_data -->|"loads"| node_tool_json
node_tool_data -->|"uses"| node_domain_types
node_app -->|"reads"| node_tool_data
node_workflow_compare -->|"reads"| node_tool_data
node_workflow_compare -->|"advances steps"| node_player_logic
node_workflow_compare -->|"renders"| node_loop_graph
node_workflow_compare -->|"renders"| node_controls
node_workflow_player -->|"reads"| node_tool_data
node_workflow_player -->|"advances steps"| node_player_logic
node_workflow_player -->|"renders"| node_loop_graph
node_workflow_player -->|"renders"| node_controls
node_loop_graph -->|"uses"| node_domain_types
node_controls -->|"controls"| node_player_logic
node_feature_matrix -->|"reads"| node_tool_data
node_heatmap -->|"reads"| node_tool_data
node_heatmap -->|"formats scores"| node_score_logic
node_heatmap -->|"renders"| node_score_pip
node_score_pip -->|"formats scores"| node_score_logic
node_tool_profile -->|"uses"| node_domain_types
node_tool_profile -->|"renders"| node_anchored_text
node_tool_profile -->|"renders"| node_score_pip
node_decision_guide -->|"reads"| node_tool_data
node_about -->|"reads"| node_tool_data
node_research_docs -->|"includes"| node_worktree_research
node_research_docs -->|"includes"| node_orchestration_research
node_research_docs -->|"informs"| node_tool_json

click node_app "https://github.com/cameronsjo/spec-compare/blob/main/site/src/App.tsx"
click node_workflow_compare "https://github.com/cameronsjo/spec-compare/blob/main/site/src/WorkflowCompare.tsx"
click node_workflow_player "https://github.com/cameronsjo/spec-compare/blob/main/site/src/WorkflowPlayer.tsx"
click node_loop_graph "https://github.com/cameronsjo/spec-compare/blob/main/site/src/LoopGraph.tsx"
click node_controls "https://github.com/cameronsjo/spec-compare/blob/main/site/src/controls.tsx"
click node_player_logic "https://github.com/cameronsjo/spec-compare/blob/main/site/src/player.ts"
click node_feature_matrix "https://github.com/cameronsjo/spec-compare/blob/main/site/src/FeatureMatrix.tsx"
click node_heatmap "https://github.com/cameronsjo/spec-compare/blob/main/site/src/ScoringHeatmap.tsx"
click node_tool_profile "https://github.com/cameronsjo/spec-compare/blob/main/site/src/ToolProfile.tsx"
click node_decision_guide "https://github.com/cameronsjo/spec-compare/blob/main/site/src/DecisionGuide.tsx"
click node_about "https://github.com/cameronsjo/spec-compare/blob/main/site/src/About.tsx"
click node_tool_data "https://github.com/cameronsjo/spec-compare/blob/main/site/src/data.ts"
click node_tool_json "https://github.com/cameronsjo/spec-compare/tree/main/site/src/data/tools"
click node_domain_types "https://github.com/cameronsjo/spec-compare/blob/main/site/src/types.ts"
click node_score_logic "https://github.com/cameronsjo/spec-compare/blob/main/site/src/score.ts"
click node_score_pip "https://github.com/cameronsjo/spec-compare/blob/main/site/src/ScorePip.tsx"
click node_anchored_text "https://github.com/cameronsjo/spec-compare/blob/main/site/src/Anchored.tsx"
click node_research_docs "https://github.com/cameronsjo/spec-compare/tree/main/docs"
click node_worktree_research "https://github.com/cameronsjo/spec-compare/blob/main/docs/git-worktree-support.md"
click node_orchestration_research "https://github.com/cameronsjo/spec-compare/blob/main/docs/landscape.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_workflow_compare,node_workflow_player,node_loop_graph,node_controls,node_player_logic,node_feature_matrix,node_heatmap,node_tool_profile,node_decision_guide,node_about,node_score_pip,node_anchored_text toneBlue
class node_tool_data,node_tool_json,node_domain_types,node_score_logic toneAmber
class node_research_docs,node_worktree_research,node_orchestration_research toneMint
class node_visitor toneIndigo
```

## Components

### Interactive site

- [Application shell](https://github.com/cameronsjo/spec-compare/blob/main/site/src/App.tsx): `site/src/App.tsx`
- [Workflow comparison](https://github.com/cameronsjo/spec-compare/blob/main/site/src/WorkflowCompare.tsx): `site/src/WorkflowCompare.tsx`
- [Workflow player](https://github.com/cameronsjo/spec-compare/blob/main/site/src/WorkflowPlayer.tsx): `site/src/WorkflowPlayer.tsx`
- [Workflow graph](https://github.com/cameronsjo/spec-compare/blob/main/site/src/LoopGraph.tsx): `site/src/LoopGraph.tsx`
- [Playback controls](https://github.com/cameronsjo/spec-compare/blob/main/site/src/controls.tsx): `site/src/controls.tsx`
- [Playback state](https://github.com/cameronsjo/spec-compare/blob/main/site/src/player.ts): `site/src/player.ts`
- [Feature matrix](https://github.com/cameronsjo/spec-compare/blob/main/site/src/FeatureMatrix.tsx): `site/src/FeatureMatrix.tsx`
- [Scoring heatmap](https://github.com/cameronsjo/spec-compare/blob/main/site/src/ScoringHeatmap.tsx): `site/src/ScoringHeatmap.tsx`
- [Tool profiles](https://github.com/cameronsjo/spec-compare/blob/main/site/src/ToolProfile.tsx): `site/src/ToolProfile.tsx`
- [Decision guide](https://github.com/cameronsjo/spec-compare/blob/main/site/src/DecisionGuide.tsx): `site/src/DecisionGuide.tsx`
- [About and disclosure](https://github.com/cameronsjo/spec-compare/blob/main/site/src/About.tsx): `site/src/About.tsx`
- [Score indicator](https://github.com/cameronsjo/spec-compare/blob/main/site/src/ScorePip.tsx): `site/src/ScorePip.tsx`
- [Emphasized text](https://github.com/cameronsjo/spec-compare/blob/main/site/src/Anchored.tsx): `site/src/Anchored.tsx`

### Comparison data

- [Tool specifications](https://github.com/cameronsjo/spec-compare/blob/main/site/src/data.ts): `site/src/data.ts`
- [Tool data files](https://github.com/cameronsjo/spec-compare/tree/main/site/src/data/tools): `site/src/data/tools`
- [Comparison model](https://github.com/cameronsjo/spec-compare/blob/main/site/src/types.ts): `site/src/types.ts`
- [Score formatting](https://github.com/cameronsjo/spec-compare/blob/main/site/src/score.ts): `site/src/score.ts`

### Research library

- [Research and analysis](https://github.com/cameronsjo/spec-compare/tree/main/docs): `docs`
- [Worktree analysis](https://github.com/cameronsjo/spec-compare/blob/main/docs/git-worktree-support.md): `docs/git-worktree-support.md`
- [Orchestration landscape](https://github.com/cameronsjo/spec-compare/blob/main/docs/landscape.md): `docs/landscape.md`

### Other components

- **Site visitor**

## Connections

- Site visitor → Application shell: opens (evidence: `README.md`)
- Application shell → Workflow comparison: routes to (evidence: `site/src/App.tsx`)
- Application shell → Workflow player: routes to (evidence: `site/src/App.tsx`)
- Application shell → Feature matrix: routes to (evidence: `site/src/App.tsx`)
- Application shell → Scoring heatmap: routes to (evidence: `site/src/App.tsx`)
- Application shell → Tool profiles: routes to (evidence: `site/src/App.tsx`)
- Application shell → Decision guide: routes to (evidence: `site/src/App.tsx`)
- Application shell → About and disclosure: routes to (evidence: `site/src/App.tsx`)
- Tool specifications → Tool data files: loads (evidence: `site/src/data.ts`)
- Tool specifications → Comparison model: uses (evidence: `site/src/data.ts`)
- Application shell → Tool specifications: reads (evidence: `site/src/App.tsx`)
- Workflow comparison → Tool specifications: reads (evidence: `site/src/WorkflowCompare.tsx`)
- Workflow comparison → Playback state: advances steps (evidence: `site/src/WorkflowCompare.tsx`)
- Workflow comparison → Workflow graph: renders (evidence: `site/src/WorkflowCompare.tsx`)
- Workflow comparison → Playback controls: renders (evidence: `site/src/WorkflowCompare.tsx`)
- Workflow player → Tool specifications: reads (evidence: `site/src/WorkflowPlayer.tsx`)
- Workflow player → Playback state: advances steps (evidence: `site/src/WorkflowPlayer.tsx`)
- Workflow player → Workflow graph: renders (evidence: `site/src/WorkflowPlayer.tsx`)
- Workflow player → Playback controls: renders (evidence: `site/src/WorkflowPlayer.tsx`)
- Workflow graph → Comparison model: uses (evidence: `site/src/LoopGraph.tsx`)
- Playback controls → Playback state: controls (evidence: `site/src/controls.tsx`)
- Feature matrix → Tool specifications: reads (evidence: `site/src/FeatureMatrix.tsx`)
- Scoring heatmap → Tool specifications: reads (evidence: `site/src/ScoringHeatmap.tsx`)
- Scoring heatmap → Score formatting: formats scores (evidence: `site/src/ScoringHeatmap.tsx`)
- Scoring heatmap → Score indicator: renders (evidence: `site/src/ScoringHeatmap.tsx`)
- Score indicator → Score formatting: formats scores (evidence: `site/src/ScorePip.tsx`)
- Tool profiles → Comparison model: uses (evidence: `site/src/ToolProfile.tsx`)
- Tool profiles → Emphasized text: renders (evidence: `site/src/ToolProfile.tsx`)
- Tool profiles → Score indicator: renders (evidence: `site/src/ToolProfile.tsx`)
- Decision guide → Tool specifications: reads (evidence: `site/src/DecisionGuide.tsx`)
- About and disclosure → Tool specifications: reads (evidence: `site/src/About.tsx`)
- Research and analysis → Worktree analysis: includes (evidence: `README.md`)
- Research and analysis → Orchestration landscape: includes (evidence: `README.md`)
- Research and analysis → Tool data files: informs (evidence: `README.md`)
