create-project-arch 1.0.0

package/templates/arch-ui/components/graph/build-graph-from-dataset.ts

@@ -0,0 +1,196 @@
+import type { Edge, Node } from "reactflow";
+import type {
+  GraphDataset,
+  GraphEdgeType,
+  GraphNodeType,
+  GraphViewMode,
+} from "../../lib/graph-schema";
+import type {
+  ArchEdgeData,
+  ArchNodeData,
+  GraphEdgeFilter,
+  GraphKind,
+  GraphTone,
+} from "./graph-types";
+
+function mapNodeTypeToKind(type: GraphNodeType): GraphKind {
+  switch (type) {
+    case "arch_folder":
+    case "domain_doc":
+    case "architecture_doc":
+      return "domain";
+    case "roadmap_folder":
+      return "phase";
+    case "architecture_model":
+      return "decision";
+    case "roadmap_epic":
+      return "phase";
+    case "roadmap_story":
+      return "milestone";
+    case "roadmap_task":
+      return "task";
+    case "project_folder":
+    case "app":
+    case "package":
+    case "module":
+    case "component":
+    default:
+      return "file";
+  }
+}
+
+function mapNodeTypeToTone(type: GraphNodeType): GraphTone {
+  switch (type) {
+    case "arch_folder":
+    case "domain_doc":
+    case "architecture_doc":
+      return "domain";
+    case "architecture_model":
+      return "decision";
+    case "roadmap_folder":
+    case "roadmap_epic":
+    case "roadmap_story":
+      return "phase";
+    case "roadmap_task":
+      return "task";
+    default:
+      return "file";
+  }
+}
+
+function mapEdgeTypeToFilter(type: GraphEdgeType): GraphEdgeFilter {
+  switch (type) {
+    case "references":
+    case "documents":
+      return "data-flow";
+    case "implements":
+      return "blocking";
+    default:
+      return "dependency";
+  }
+}
+
+const typeColumn: Record<GraphNodeType, number> = {
+  arch_folder: 0,
+  domain_doc: 1,
+  architecture_doc: 2,
+  architecture_model: 3,
+  roadmap_folder: 0,
+  roadmap_epic: 1,
+  roadmap_story: 2,
+  roadmap_task: 3,
+  project_folder: 0,
+  app: 1,
+  package: 2,
+  module: 3,
+  component: 4,
+};
+
+function estimateNodeHeight(node: GraphDataset["nodes"][number]): number {
+  // Keep estimates stable and deterministic so structure remains predictable.
+  const base = 92;
+  const titleLines = Math.max(1, Math.ceil(node.title.length / 26));
+  const subtitleLines = node.description ? Math.max(1, Math.ceil(node.description.length / 36)) : 0;
+  const metadataLines = Math.min(3, Math.max(1, Object.keys(node.metadata).length));
+  return base + titleLines * 16 + subtitleLines * 14 + metadataLines * 12;
+}
+
+function estimateNodeWidth(node: GraphDataset["nodes"][number]): number {
+  const base = 220;
+  const titleWidth = node.title.length * 7.2;
+  const subtitleWidth = (node.description ?? "").length * 6.4;
+  const metadataStrings = Object.entries(node.metadata).map(([key, value]) => {
+    const normalized = Array.isArray(value) ? value.join(", ") : String(value);
+    return `${key}: ${normalized}`;
+  });
+  const metadataWidth = metadataStrings.reduce((max, value) => Math.max(max, value.length * 6.8), 0);
+  const estimated = base + Math.max(titleWidth, subtitleWidth, metadataWidth) * 0.58;
+  return Math.max(240, Math.min(estimated, 760));
+}
+
+export function buildGraphFromDataset(
+  dataset: GraphDataset,
+  _viewMode: GraphViewMode,
+): { nodes: Node<ArchNodeData>[]; edges: Edge<ArchEdgeData>[] } {
+  const indexByType = new Map<GraphNodeType, number>();
+  const columnCursorY = new Map<number, number>();
+  const columnMaxWidth = new Map<number, number>();
+  const columnX = new Map<number, number>();
+  const VERTICAL_GAP = 34;
+  const MIN_HORIZONTAL_GAP = 110;
+  const START_Y = 40;
+  const START_X = 120;
+
+  dataset.nodes.forEach((node) => {
+    const column = typeColumn[node.type];
+    const width = estimateNodeWidth(node);
+    const currentMax = columnMaxWidth.get(column) ?? 0;
+    if (width > currentMax) columnMaxWidth.set(column, width);
+  });
+
+  const columns = [...new Set(dataset.nodes.map((node) => typeColumn[node.type]))].sort(
+    (a, b) => a - b,
+  );
+  let cursorX = START_X;
+  columns.forEach((column, index) => {
+    columnX.set(column, cursorX);
+    const currentWidth = columnMaxWidth.get(column) ?? 260;
+    const nextColumn = columns[index + 1];
+    const nextWidth = nextColumn === undefined ? currentWidth : (columnMaxWidth.get(nextColumn) ?? 260);
+    const adaptiveGap = Math.max(
+      MIN_HORIZONTAL_GAP,
+      Math.round(Math.max(currentWidth, nextWidth) * 0.24),
+    );
+    cursorX += currentWidth + adaptiveGap;
+  });
+
+  const nodes: Node<ArchNodeData>[] = dataset.nodes.map((node) => {
+    const count = indexByType.get(node.type) ?? 0;
+    indexByType.set(node.type, count + 1);
+    const column = typeColumn[node.type];
+    const currentY = columnCursorY.get(column) ?? START_Y;
+    const height = estimateNodeHeight(node);
+    columnCursorY.set(column, currentY + height + VERTICAL_GAP);
+
+    return {
+      id: node.id,
+      type: "archNode",
+      position: {
+        x: columnX.get(column) ?? START_X + column * 320,
+        y: currentY,
+      },
+      data: {
+        kind: mapNodeTypeToKind(node.type),
+        tone: mapNodeTypeToTone(node.type),
+        label: node.title,
+        subtitle: node.description,
+        canonicalType: node.type,
+        metadata: [
+          { label: "Node Type", value: node.type },
+          { label: "Source", value: node.source.path },
+          { label: "Scope", value: node.source.scope },
+          ...Object.entries(node.metadata).map(([key, value]) => ({
+            label: key,
+            value: Array.isArray(value) ? value.join(", ") : String(value),
+          })),
+        ],
+      },
+    };
+  });
+
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const edges: Edge<ArchEdgeData>[] = dataset.edges
+    .filter((edge) => nodeIds.has(edge.source) && nodeIds.has(edge.target))
+    .map((edge) => ({
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+      type: "smoothstep",
+      data: {
+        edgeType: mapEdgeTypeToFilter(edge.type),
+        authority: edge.authority,
+      },
+    }));
+
+  return { nodes, edges };
+}

package/templates/arch-ui/components/graph/build-initial-graph.ts

@@ -0,0 +1,245 @@
+import type { Edge, Node } from "reactflow";
+import type { ArchitectureMapData } from "../../lib/types";
+import type {
+    ArchEdgeData,
+    ArchNodeData,
+    GraphFilter,
+    GraphKind,
+    GraphTone,
+} from "./graph-types";
+
+function createGraphNode(
+    kind: GraphKind,
+    id: string,
+    x: number,
+    y: number,
+    label: string,
+    tone: GraphTone,
+    subtitle?: string,
+    metadata: Array<{ label: string; value: string }> = [],
+): Node<ArchNodeData> {
+    return {
+        id: `${kind}:${id}`,
+        type: "archNode",
+        position: { x, y },
+        data: { kind, tone, label, subtitle, metadata },
+    };
+}
+
+export function buildInitialGraph(
+    data: ArchitectureMapData,
+    enabledFilters: GraphFilter[],
+    hideCompletedTasks = false,
+): { nodes: Node<ArchNodeData>[]; edges: Edge[] } {
+    const includeDomains = enabledFilters.includes("domains");
+    const includeModules = enabledFilters.includes("modules");
+    const includeTasks = enabledFilters.includes("tasks");
+    const includeDecisions = enabledFilters.includes("decisions");
+
+    const milestoneTaskCount = new Map<string, number>();
+    data.edges.milestoneToTask.forEach((edge) => {
+        milestoneTaskCount.set(edge.milestone, (milestoneTaskCount.get(edge.milestone) ?? 0) + 1);
+    });
+
+    const decisionTaskCount = new Map<string, number>();
+    data.edges.taskToDecision.forEach((edge) => {
+        decisionTaskCount.set(edge.decision, (decisionTaskCount.get(edge.decision) ?? 0) + 1);
+    });
+
+    const moduleTaskCount = new Map<string, number>();
+    data.edges.taskToModule.forEach((edge) => {
+        moduleTaskCount.set(edge.module, (moduleTaskCount.get(edge.module) ?? 0) + 1);
+    });
+
+    const domainDecisionCount = new Map<string, number>();
+    data.edges.decisionToDomain.forEach((edge) => {
+        domainDecisionCount.set(edge.domain, (domainDecisionCount.get(edge.domain) ?? 0) + 1);
+    });
+
+    const nodes: Node<ArchNodeData>[] = [];
+    const edges: Edge<ArchEdgeData>[] = [];
+
+    if (includeDomains) {
+        data.nodes.domains.forEach((domain, index) => {
+            nodes.push(
+                createGraphNode(
+                    "domain",
+                    domain.name,
+                    40,
+                    40 + index * 140,
+                    domain.name,
+                    "domain",
+                    domain.description,
+                    [
+                        { label: "Description", value: domain.description ?? "n/a" },
+                        { label: "Decisions", value: String(domainDecisionCount.get(domain.name) ?? 0) },
+                        { label: "Graph Node", value: `domain:${domain.name}` },
+                    ],
+                ),
+            );
+        });
+    }
+
+    if (includeDecisions) {
+        data.nodes.decisions.forEach((decision, index) => {
+            nodes.push(
+                createGraphNode(
+                    "decision",
+                    decision.id,
+                    280,
+                    40 + index * 140,
+                    decision.id,
+                    "decision",
+                    decision.title,
+                    [
+                        { label: "Title", value: decision.title ?? decision.id },
+                        { label: "Status", value: decision.status ?? "open" },
+                        { label: "Linked Tasks", value: String(decisionTaskCount.get(decision.id) ?? 0) },
+                        { label: "Graph Node", value: `decision:${decision.id}` },
+                    ],
+                ),
+            );
+        });
+    }
+
+    const phases = [...new Set(data.nodes.milestones.map((item) => item.phaseId))];
+    phases.forEach((phase, index) => {
+        const phaseMilestones = data.nodes.milestones.filter(
+            (milestone) => milestone.phaseId === phase,
+        ).length;
+        nodes.push(
+            createGraphNode("phase", phase, 520, 40 + index * 140, phase, "phase", undefined, [
+                { label: "Milestones", value: String(phaseMilestones) },
+                { label: "Graph Node", value: `phase:${phase}` },
+            ]),
+        );
+    });
+
+    data.nodes.milestones.forEach((milestone, index) => {
+        nodes.push(
+            createGraphNode(
+                "milestone",
+                milestone.id,
+                760,
+                40 + index * 140,
+                milestone.id,
+                "phase",
+                milestone.phaseId,
+                [
+                    { label: "Phase", value: milestone.phaseId },
+                    { label: "Milestone", value: milestone.milestoneId },
+                    { label: "Tasks", value: String(milestoneTaskCount.get(milestone.id) ?? 0) },
+                    { label: "Graph Node", value: `milestone:${milestone.id}` },
+                ],
+            ),
+        );
+        edges.push({
+            id: `phase-milestone:${milestone.phaseId}-${milestone.id}`,
+            source: `phase:${milestone.phaseId}`,
+            target: `milestone:${milestone.id}`,
+            type: "smoothstep",
+            data: { edgeType: "blocking", authority: "authoritative" },
+        });
+    });
+
+    const visibleTasks = data.nodes.tasks.filter(
+        (task) => !(hideCompletedTasks && task.lane === "complete"),
+    );
+
+    if (includeTasks) {
+        visibleTasks.forEach((task, index) => {
+            nodes.push(
+                createGraphNode("task", task.id, 1020, 40 + index * 120, task.title, "task", task.id, [
+                    { label: "ID", value: task.id },
+                    { label: "Milestone", value: task.milestone },
+                    { label: "Lane", value: task.lane },
+                    { label: "Status", value: task.status },
+                    { label: "Domain", value: task.domain ?? "unassigned" },
+                    { label: "Graph Node", value: `task:${task.id}` },
+                ]),
+            );
+        });
+    }
+
+    if (includeModules) {
+        data.nodes.modules.forEach((moduleRef, index) => {
+            nodes.push(
+                createGraphNode(
+                    "file",
+                    moduleRef.name,
+                    1280,
+                    40 + index * 100,
+                    moduleRef.name,
+                    "file",
+                    moduleRef.type,
+                    [
+                        { label: "Name", value: moduleRef.name },
+                        { label: "Type", value: moduleRef.type ?? "module" },
+                        { label: "Description", value: moduleRef.description ?? "n/a" },
+                        { label: "Linked Tasks", value: String(moduleTaskCount.get(moduleRef.name) ?? 0) },
+                        { label: "Graph Node", value: `file:${moduleRef.name}` },
+                    ],
+                ),
+            );
+        });
+    }
+
+    if (includeTasks) {
+        data.edges.milestoneToTask.forEach((edge) => {
+            if (!visibleTasks.some((task) => task.id === edge.task)) return;
+            edges.push({
+                id: `milestone-task:${edge.milestone}-${edge.task}`,
+                source: `milestone:${edge.milestone}`,
+                target: `task:${edge.task}`,
+                type: "smoothstep",
+                data: { edgeType: "blocking", authority: "authoritative" },
+            });
+        });
+    }
+
+    if (includeDecisions && includeDomains) {
+        data.edges.decisionToDomain.forEach((edge) => {
+            edges.push({
+                id: `decision-domain:${edge.decision}-${edge.domain}`,
+                source: `decision:${edge.decision}`,
+                target: `domain:${edge.domain}`,
+                type: "smoothstep",
+                data: { edgeType: "data-flow", authority: "authoritative" },
+            });
+        });
+    }
+
+    if (includeTasks && includeModules) {
+        data.edges.taskToModule.forEach((edge) => {
+            if (!visibleTasks.some((task) => task.id === edge.task)) return;
+            edges.push({
+                id: `task-module:${edge.task}-${edge.module}`,
+                source: `task:${edge.task}`,
+                target: `file:${edge.module}`,
+                type: "smoothstep",
+                data: { edgeType: "dependency", authority: "authoritative" },
+            });
+        });
+    }
+
+    if (includeTasks && includeDecisions) {
+        data.edges.taskToDecision.forEach((edge) => {
+            if (!visibleTasks.some((task) => task.id === edge.task)) return;
+            edges.push({
+                id: `task-decision:${edge.task}-${edge.decision}`,
+                source: `task:${edge.task}`,
+                target: `decision:${edge.decision}`,
+                type: "smoothstep",
+                data: { edgeType: "blocking", authority: "authoritative" },
+            });
+        });
+    }
+
+    edges.forEach((edge) => {
+        if (!edge.data) {
+            edge.data = { edgeType: "dependency", authority: "authoritative" };
+        }
+    });
+
+    return { nodes, edges };
+}

package/templates/arch-ui/components/graph/graph-context-menu.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import type { Node, ReactFlowInstance } from "reactflow";
+import type { ArchNodeData, ContextMenuState, InspectorNode } from "./graph-types";
+import { buildNodeMarkdown, parseNodeId } from "./graph-types";
+
+type GraphContextMenuProps = {
+  contextMenu: ContextMenuState;
+  node: Node<ArchNodeData>;
+  flowInstance: ReactFlowInstance<ArchNodeData> | null;
+  onInspect: (node: InspectorNode) => void;
+  onHideNode: (nodeId: string) => void;
+  onShowAll: () => void;
+  onClose: () => void;
+};
+
+export function GraphContextMenu({
+  contextMenu,
+  node,
+  flowInstance,
+  onInspect,
+  onHideNode,
+  onShowAll,
+  onClose,
+}: GraphContextMenuProps) {
+  function inspect() {
+    const parsed = parseNodeId(node.id);
+    onInspect({
+      type: parsed.kind,
+      id: parsed.id,
+      title: node.data.label,
+      metadata: node.data.metadata,
+      markdown: buildNodeMarkdown(node),
+    });
+    onClose();
+  }
+
+  return (
+    <div
+      className="fixed z-[100] grid min-w-40 gap-1 rounded-lg border border-slate-600 bg-slate-950 p-1.5"
+      style={{ top: contextMenu.y, left: contextMenu.x }}
+    >
+      <button
+        type="button"
+        className="cursor-pointer rounded-md border border-transparent px-2 py-1.5 text-left text-sm hover:border-slate-600 hover:bg-slate-800"
+        onClick={inspect}
+      >
+        Inspect node
+      </button>
+      <button
+        type="button"
+        className="cursor-pointer rounded-md border border-transparent px-2 py-1.5 text-left text-sm hover:border-slate-600 hover:bg-slate-800"
+        onClick={() => {
+          if (flowInstance) {
+            flowInstance.fitView({ nodes: [{ id: node.id }], duration: 300 });
+          }
+          onClose();
+        }}
+      >
+        Center node
+      </button>
+      <button
+        type="button"
+        className="cursor-pointer rounded-md border border-transparent px-2 py-1.5 text-left text-sm hover:border-slate-600 hover:bg-slate-800"
+        onClick={() => {
+          onHideNode(node.id);
+          onClose();
+        }}
+      >
+        Hide node
+      </button>
+      <button
+        type="button"
+        className="cursor-pointer rounded-md border border-transparent px-2 py-1.5 text-left text-sm hover:border-slate-600 hover:bg-slate-800"
+        onClick={() => {
+          onShowAll();
+          onClose();
+        }}
+      >
+        Show all nodes
+      </button>
+    </div>
+  );
+}

package/templates/arch-ui/components/graph/graph-doc-panel.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { Panel } from "reactflow";
+import type { Node } from "reactflow";
+import type { ArchNodeData, InspectorNode } from "./graph-types";
+import { buildNodeMarkdown, parseNodeId } from "./graph-types";
+import { MarkdownViewer } from "../markdown-viewer";
+
+type GraphDocPanelProps = {
+  node: Node<ArchNodeData>;
+  markdown: string;
+  onInspect: (node: InspectorNode) => void;
+  onClose: () => void;
+};
+
+export function GraphDocPanel({ node, markdown, onInspect, onClose }: GraphDocPanelProps) {
+  function openDetail() {
+    const parsed = parseNodeId(node.id);
+    onInspect({
+      type: parsed.kind,
+      id: parsed.id,
+      title: node.data.label,
+      metadata: node.data.metadata,
+      markdown: buildNodeMarkdown(node),
+    });
+  }
+
+  return (
+    <Panel position="top-right">
+      <div className="graph-doc-panel">
+        <div className="row-between">
+          <strong>Node Notes</strong>
+          <div className="row-wrap">
+            <button className="ui-btn ui-btn-outline" type="button" onClick={openDetail}>
+              Open Detail
+            </button>
+            <button className="ui-btn ui-btn-ghost" type="button" onClick={onClose}>
+              Close
+            </button>
+          </div>
+        </div>
+        <MarkdownViewer markdown={markdown} />
+      </div>
+    </Panel>
+  );
+}

package/templates/arch-ui/components/graph/graph-types.ts

@@ -0,0 +1,82 @@
+import type { Node } from "reactflow";
+
+export type GraphFilter = "domains" | "modules" | "tasks" | "decisions";
+export type GraphEdgeFilter = "dependency" | "data-flow" | "blocking";
+export type GraphEdgeAuthority = "authoritative" | "manual" | "inferred";
+export type GraphCanvasViewMode = "architecture-map" | "tasks" | "project";
+export type GraphKind = "domain" | "decision" | "phase" | "milestone" | "task" | "file";
+export type GraphTone = "domain" | "decision" | "phase" | "task" | "file";
+
+export type InspectorNode = {
+    type: string;
+    id: string;
+    title: string;
+    metadata: Array<{ label: string; value: string }>;
+    markdown?: string;
+};
+
+export type ArchNodeData = {
+    kind: GraphKind;
+    tone: GraphTone;
+    label: string;
+    subtitle?: string;
+    canonicalType?: string;
+    metadata: Array<{ label: string; value: string }>;
+};
+
+export type ArchEdgeData = {
+    edgeType: GraphEdgeFilter;
+    authority: GraphEdgeAuthority;
+};
+
+export type ContextMenuState = {
+    nodeId: string;
+    x: number;
+    y: number;
+};
+
+export const NODE_WIDTH = 220;
+export const NODE_HEIGHT = 100;
+
+export const toneColor: Record<GraphTone, string> = {
+    domain: "#3b82f6",
+    decision: "#7c3aed",
+    phase: "#22c55e",
+    task: "#f59e0b",
+    file: "#6b7280",
+};
+
+export function parseNodeId(nodeId: string): { kind: GraphKind; id: string } {
+    const [scope = "file", type = "file", ...rest] = nodeId.split(":");
+    if (scope === "roadmap" && type === "task") return { kind: "task", id: rest.join(":") };
+    if (scope === "roadmap" && type === "story") return { kind: "milestone", id: rest.join(":") };
+    if (scope === "roadmap" && type === "epic") return { kind: "phase", id: rest.join(":") };
+    if (scope === "arch" && type === "domain") return { kind: "domain", id: rest.join(":") };
+    if (scope === "arch" && type === "doc") return { kind: "domain", id: rest.join(":") };
+    if (scope === "arch" && type === "model") return { kind: "decision", id: rest.join(":") };
+    if (scope === "project") return { kind: "file", id: rest.join(":") };
+    const kind = (scope as GraphKind) || "file";
+    return { kind, id: [type, ...rest].filter(Boolean).join(":") };
+}
+
+export function buildNodeMarkdown(node: Node<ArchNodeData>): string {
+    const { kind, label, subtitle, metadata } = node.data;
+    const identity = parseNodeId(node.id);
+    const metadataMarkdown =
+        metadata.length > 0
+            ? metadata.map((item) => `- **${item.label}**: ${item.value}`).join("\n")
+            : "- No metadata available";
+
+    return [
+        `## ${label}`,
+        "",
+        `- **Type**: ${kind}`,
+        `- **ID**: \`${identity.id}\``,
+        subtitle ? `- **Subtitle**: ${subtitle}` : "",
+        "",
+        "### Metadata",
+        metadataMarkdown,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}