>> zephyr workbench
Architecture is usually described after it is decided. The diagram comes after the call. The slide after the build. By the time anyone reviews the model, the system has already moved on.
Zephyr Workbench inverts this. It is a YAML-based CLI that makes architecture executable — something you write before you build, validate before you present, and diff before you merge. The model is not the documentation. It is the specification.
The contract is minimal: components, flows, and optionally risks, controls, and stakeholders. You describe what exists, what connects to what, and where the gaps are. Zephyr validates the structure, surfaces the warnings, and renders a diagram. In one command.
The validation engine is where the tool earns its keep. It knows what a single access-gateway implies — a single point of failure. It recognizes when an endpoint talks directly to another endpoint. It reads the structure and flags the patterns that suggest problems before you deploy them. The warnings are structural observations, not style suggestions.
The diff subcommand is the most interesting decision.
Compare two architecture models and it exits with a non-zero code if they diverge —
which means architecture drift becomes a CI failure.
That is a strong claim: if the infrastructure moves away from the model,
the build breaks. The model is not optional.
One runtime dependency: PyYAML. No build system, no account, no cloud. A YAML file, a terminal, and a schema. That constraint is not a limitation — it is a design choice. The tool is small because the problem is precise.
Model first. Diagram later. Most architecture work runs in the opposite direction. That is why most architecture work is hard to trust.