developer tooling · CI/CD · graph algorithms · 2026 · Solo — product framing, parse engine, SVG layout, GitHub API integration, TDD, deployment
Flow Form
A workflow-commit tool that parses live GitHub Actions YAML into a typed DAG, renders an editorial dependency diagram, and commits it back to the repository via the GitHub Contents API.
The problem
GitHub Actions workflow files encode complex parallelism and sequencing graphs in YAML. Developers read them linearly but reason about them visually. No standard tool reads live workflow YAML from a repo without cloning, parses jobs[].needs[] into a real DAG, renders a clean diagram without Mermaid auto-layout, and commits the result back to the repo so it stays co-located with the source. Flow Form does all four. The parse engine extracts a typed JobGraph from js-yaml output, a custom topological layout assigns layers using Kahn's algorithm with Sugiyama-style column packing, and the rendered SVG is committed via the GitHub Contents API with correct base64 encoding and existing-file-SHA resolution for idempotent updates. The tool has 17 TDD unit tests covering the parse engine and SVG renderer before any UI code existed.
Architecture
Key decisions
Custom DAG layout without external libraries
The parse engine implements Kahn's topological sort from scratch to detect cycles and assign parallel layers. Column packing uses a simple greedy approach. No graphviz, dagre, or Mermaid was used. This keeps the bundle browser-local and forces understanding of the graph structure at the implementation level — a deliberate engineering choice for interview depth.
Operate surface, not Decide/Learn
The product is a commit tool, not a diagram viewer. The diagram preview is a step in the commit flow, not the destination. The primary CTA is 'Commit SVG to repo.' This surfaces the real-world value (a durable artifact in the repo) rather than a transient inspection.
TDD-first parse and SVG engine
All 17 tests were written before the parse engine and SVG renderer existed. Tests cover: root job detection, needs[] edge parsing, diamond dependencies, layer assignment for parallel jobs, SVG string return, correct node count, edge paths, layer-0 x position, single-job layout, and empty graph. The tests caught a subtle bug where needs could be a string instead of an array in some workflow formats.
cathrynlavery visual grammar
The SVG uses cathrynlavery design principles applied from scratch: no shadows, accent reserved for critical path edges (amber), density 4/10, nodes earn their place. The background is warm parchment (#FAFAF8), nodes are clean white rectangles with ink labels, and the overall aesthetic is editorial CI-paper rather than a generic diagram tool.