architecture-workbench 0.1.1

Spec-first CLI that turns a plain-language system idea into a validated architecture, flows, and a feasibility review using an LLM.

Architecture Workbench (AWB)

From Business Ideas to Explainable Architecture

Software architecture is still largely a manual process.

Business ideas become documents.

Documents become meetings.

Meetings become diagrams.

Diagrams become implementations.

Knowledge is often scattered across documents, presentations, tickets, and architects' experience.

As systems become increasingly distributed, cloud-native, and AI-enabled, architecture becomes harder to communicate, review, reproduce, and evolve.

Architecture Workbench (AWB) is an attempt to change that.

Rather than treating architecture as a collection of diagrams, AWB treats architecture as an engineering discipline built on structured models, reusable knowledge, and explainable decision making.

---

The Problem

Today's AI tools can generate architecture diagrams from prompts.

However, they rarely answer questions such as:

• Why was this architecture chosen?
• Which business requirement does this component satisfy?
• Which assumptions were made?
• Which architecture pattern was applied?
• Can another architect reproduce the same result?
• Can the architecture be reviewed automatically?

Without a structured process, architecture becomes difficult to validate, evolve, and maintain.

---

Our Vision

Architecture Workbench is designed as an Architecture Compiler.

Instead of generating architecture directly from natural language, AWB transforms business intent into architecture through a series of well-defined engineering stages.

Business Idea
        │
        ▼
Architecture Discovery
        │
        ▼
Canonical Requirement
        │
        ▼
Architecture Knowledge
        │
        ▼
Canonical Architecture
        │
        ▼
Views & Reviews

Each stage produces a well-defined artifact that can be reviewed, versioned, tested, and improved independently.

---

Core Philosophy

Specification First

Every implementation begins with a specification.

Specification
        ↓
Example
        ↓
Schema
        ↓
Implementation

The model is designed first.

Code comes later.

---

Knowledge First

Architecture should be based on reusable engineering knowledge rather than isolated prompts.

Patterns, best practices, and architectural experience are treated as reusable assets.

---

Architecture as Code

Architecture should be managed like software.

Architecture artifacts should be:

• Version controlled
• Reviewable
• Reproducible
• Testable
• Explainable

Documents are no longer the final output—they become part of an engineering workflow.

---

Simple First

Start with the smallest model that solves the problem.

Complexity is introduced only when justified by real-world requirements.

---

Human in the Loop

AWB assists architects.

It does not replace architectural judgement.

Every recommendation should remain transparent, explainable, and reviewable.

---

Canonical Models

AWB separates architectural thinking into independent models.

Each model has a single responsibility.

Discovery
        │
        ▼
Requirement Model
        │
        ▼
Architecture Model
        │
        ▼
Workflow Model
        │
        ▼
Review Model

Because these models are independent, they can evolve without breaking the rest of the platform.

---

Architecture Pipeline

The current Architecture Workbench workflow is intentionally simple.

Business Idea
        │
        ▼
Discovery
        │
        ▼
Requirement
(requirement.yaml)
        │
        ▼
Architecture Knowledge
        │
        ▼
Architecture
(architecture.yaml)
        │
        ├────────────► Workflow
        ├────────────► Diagrams
        └────────────► Architecture Review

The canonical architecture becomes the single source of truth.

Everything else is generated from it.

---

Repository Structure

docs/
│
├── INDEX.md
├── adr/
├── architecture/
└── roadmap/

examples/

skills/

src/awb/schemas/

src/

workflows/

The repository is organised around architecture artifacts rather than implementation details.

---

Documentation

The documentation is organised into several layers.

Document	Purpose
README.md	Project overview and vision
docs/INDEX.md	Documentation entry point
docs/adr/	Architecture Decision Records
docs/architecture/	Core architecture models
docs/architecture/discovery/	Discovery Catalog
docs/architecture/knowledge/	Architecture Knowledge Catalog
docs/roadmap/	Product roadmap and sprint planning

---

See It In Action

Given a plain-language idea in input.md:

awb run examples/fleet-tracker --generate --provider openrouter --model deepseek/deepseek-v4-flash

Generating requirement.yaml from examples/fleet-tracker/input.md using deepseek/deepseek-v4-flash...
Generating architecture.yaml from examples/fleet-tracker/requirement.yaml using deepseek/deepseek-v4-flash...
Generating flows.yaml from examples/fleet-tracker/architecture.yaml using deepseek/deepseek-v4-flash...
Generating review.yaml/review.md from examples/fleet-tracker using deepseek/deepseek-v4-flash...
Architecture Workbench pipeline completed.
Example: examples/fleet-tracker
Generated diagrams:
  - diagrams/logical-architecture.mmd
  - diagrams/data-flow.mmd
  - diagrams/sequence-flow.mmd
Review outputs:
  - review.yaml
  - review.md

...AWB produces a validated, schema-checked architecture — including a logical diagram rendered straight from architecture.yaml, with no hand-drawing involved:

flowchart LR
    Driver[Driver]
    Dispatcher[Dispatcher]
    Finance_Staff[Finance Staff]
    Fleet_Tracker_System[Fleet Tracker System]
    Driver_App[Driver App]
    GPS_Ingestion_Service[GPS Ingestion Service]
    Route_Deviation_Detector[Route Deviation Detector]
    Stuck_Vehicle_Detector[Stuck Vehicle Detector]
    Alert_Service[Alert Service]
    Dispatcher_Web_Dashboard[Dispatcher Web Dashboard]
    Delivery_Status_Service[Delivery Status Service]
    RoutePilot_Integration_Service[RoutePilot Integration Service]
    Reporting_Service[Reporting Service]
    Photo_Storage[Photo Storage]
    GPS_Location_Database[(GPS Location Database)]
    Route_Database[(Route Database)]
    Delivery_Status_Database[(Delivery Status Database)]
    Alert_Database[(Alert Database)]
    RoutePilot[RoutePilot]

    Driver_App -->|HTTPS| GPS_Ingestion_Service
    Driver_App -->|HTTPS| Delivery_Status_Service
    RoutePilot_Integration_Service -->|HTTPS| RoutePilot
    GPS_Ingestion_Service -->|internal| GPS_Location_Database
    GPS_Ingestion_Service -->|event| Route_Deviation_Detector
    GPS_Ingestion_Service -->|event| Stuck_Vehicle_Detector
    Route_Deviation_Detector -->|event| Alert_Service
    Stuck_Vehicle_Detector -->|event| Alert_Service
    Alert_Service -->|internal| Alert_Database
    Alert_Service -->|WebSocket| Dispatcher_Web_Dashboard
    RoutePilot_Integration_Service -->|internal| Route_Database
    Route_Deviation_Detector -->|internal| Route_Database
    Delivery_Status_Service -->|internal| Delivery_Status_Database
    Delivery_Status_Service -->|internal| Photo_Storage
    Dispatcher_Web_Dashboard -->|internal| Delivery_Status_Database
    Reporting_Service -->|internal| Delivery_Status_Database
    GPS_Ingestion_Service -->|WebSocket| Dispatcher_Web_Dashboard
    Dispatcher -->|HTTPS| Dispatcher_Web_Dashboard
    Finance_Staff -->|HTTPS| Reporting_Service

Alongside the diagram, AWB also produces a flows.yaml (data/sequence flows) and an automated review.md — a feasibility assessment with severity-ranked findings (security, scalability, availability, observability, data governance...) and concrete recommendations, generated from the architecture itself rather than hand-written.

---

Example Projects

The repository includes eight end-to-end examples spanning different domains, scales, and deployment constraints — used to stress-test the generation pipeline, not just demo it:

Example	Domain
examples/ai-portal	Internal enterprise AI portal (SharePoint/S3/LLM)
examples/fleet-tracker	Delivery fleet GPS tracking and alerting
examples/book-club	Small community app, no AI angle
examples/streaming-platform	Large-scale live video streaming (millions of concurrent viewers)
examples/clinic-records	On-premises healthcare records, regulated & offline-first
examples/vn-ocr-bfi	Vietnamese OCR for banking/finance/insurance, regulated & deployment-flexible
examples/helpdesk-saas	Multi-tenant B2B helpdesk SaaS
examples/plant-predictive-maintenance	Manufacturing plant predictive maintenance & production monitoring, edge-first, read-only OT integration

Each one goes through the same complete workflow:

input.md
        │
        ▼
requirement.yaml
        │
        ▼
architecture.yaml
        │
        ▼
flows.yaml
        │
        ▼
review.yaml + review.md
        │
        ▼
Mermaid Diagrams

---

Quick Start

Clone the repository, create a virtual environment, and install the project.

git clone <repository-url>
cd architecture-workbench

python -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"

Run the checked-in example pipeline (validate + render diagrams, no LLM call).

awb run examples/ai-portal

Generate a new architecture from your own idea, end to end, using an LLM. This needs an API key — copy .env.example to .env and fill in the key for whichever provider you use (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or AWS credentials for Bedrock).

awb init my-project
# edit examples/my-project/input.md with your system idea, then:
awb run examples/my-project --generate --provider openrouter --model deepseek/deepseek-v4-flash

Run individual pipeline steps, validate, or render on their own.

awb generate examples/my-project --step architecture --provider openrouter --model deepseek/deepseek-v4-flash
awb validate examples/my-project
awb render examples/my-project

Run the test suite.

pytest

---

Running with Docker

No local Python setup needed — build the image once and run awb through it.

docker build -t architecture-workbench .

Run the checked-in example (no LLM call, no API key needed):

docker run --rm architecture-workbench validate examples/ai-portal

Generate from your own idea — mount a host directory so the output persists past the container, and pass your .env for the API key:

docker run --rm -v "$(pwd)/examples:/app/examples" --env-file .env architecture-workbench \
  init my-project

# edit examples/my-project/input.md on the host, then:
docker run --rm -v "$(pwd)/examples:/app/examples" --env-file .env architecture-workbench \
  run examples/my-project --generate --provider openrouter --model deepseek/deepseek-v4-flash

The image is built from python:3.13-slim and targets both linux/amd64 and linux/arm64 — if you're publishing it (Docker Hub, GHCR, etc.) from an Apple Silicon Mac, build for both platforms explicitly with buildx rather than a plain docker build, or anyone running it on a typical x86_64 server/CI runner will get slow emulation instead of a native image:

docker buildx build --platform linux/amd64,linux/arm64 -t architecture-workbench --push .

---

Current Status

The project currently provides:

• LLM-backed generation for every pipeline stage — requirement, architecture, flows, review — each validated against a JSON Schema and retried with the validator's own errors on failure (schema-as-guardrail, not hand-written rules)
• Three interchangeable LLM backends: direct Anthropic API, AWS Bedrock, and OpenRouter (for DeepSeek, GLM, and other models), behind a single minimal provider interface
• Automatic recovery from truncated model output (doubles the token budget and retries) and from earlier-discovered failure modes: fabricated placeholder values for empty lists, invented specific regulations/certifications, and invented numeric KPIs the input never stated
• awb run --generate — the full input.md → requirement → architecture → flows → review + diagrams pipeline in one command
• Eight end-to-end example projects spanning different scales, domains, and deployment constraints (see Example Projects above)
• A multi-arch (linux/amd64/linux/arm64) Docker image — no local Python setup required
• A test suite (schema validation, diagram rendering, CLI smoke tests, and unit tests for the generation/retry logic with no LLM calls required) running in CI on every push
• Architecture Decision Records, a canonical domain model, and a documented pipeline philosophy (docs/)
• MIT licensed

Future releases will expand from here — see the roadmap below.

---

Long-Term Roadmap

Deliberately not built yet, in rough order of when we'd expect to revisit them:

• Richer clarifying-question scoping per domain (see docs/guides/clarifying-questions-by-domain.md)
• A thin web UI over the existing generation pipeline, once the underlying generation quality has been proven out further — not before
• Cost/sizing estimation grounded in real, current cloud pricing data (not model-recalled numbers)
• Multi-cloud reference architectures
• Threat modeling
• Architecture evolution / diffing between versions
• Multi-agent collaboration
• Architecture governance

---

Guiding Principle

Architecture Workbench is not a diagram generator.

Architecture Workbench is an engineering platform that transforms business intent into explainable architecture through canonical models, reusable knowledge, and structured workflows.

Every artifact should be:

• Understandable
• Traceable
• Reviewable
• Reproducible
• Evolvable

The goal is not simply to generate architecture.

The goal is to make architecture a first-class engineering discipline.