Metadata-Version: 2.4
Name: architecture-workbench
Version: 0.2.0
Summary: Spec-first CLI that turns a plain-language system idea into a validated architecture, flows, and a feasibility review using an LLM.
Author: Viet Hoang
License-Expression: MIT
Project-URL: Homepage, https://github.com/viethoang35/architecture-workbench
Project-URL: Repository, https://github.com/viethoang35/architecture-workbench
Project-URL: Issues, https://github.com/viethoang35/architecture-workbench/issues
Keywords: architecture,llm,cli,codegen,solution-architecture,anthropic,openrouter
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: jsonschema>=4.0
Requires-Dist: anthropic[bedrock]>=0.90.0
Requires-Dist: httpx>=0.24
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# Architecture Workbench (AWB)

> **From Business Ideas to Explainable Architecture**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/architecture-workbench.svg)](https://pypi.org/project/architecture-workbench/)

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.

```text
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.

```text
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.

```text
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.

```text
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

```text
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                   |
| `src/awb/knowledge/patterns/`  | Architecture Knowledge Catalog — wired into `architecture-sketch` |
| `docs/roadmap/`                | Product roadmap and sprint planning |

---

# See It In Action

Given a plain-language idea in `input.md`:

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

```text
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:

```mermaid
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:

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

---

# Quick Start

Install from PyPI if you just want the `awb` CLI for your own projects:

```bash
pip install architecture-workbench
awb init my-project
```

To work with the checked-in example projects, run the test suite, or contribute, clone the
repository instead:

```bash
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).

```bash
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).

```bash
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.

```bash
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.

```bash
pytest
```

---

# Running with Docker

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

```bash
docker build -t architecture-workbench .
```

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

```bash
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:

```bash
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:

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

---

# Using as a GitHub Action

The same Docker image doubles as a GitHub Action, so you can run `awb` against your own repository
in CI — for example, validating that `requirement.yaml` still matches its schema whenever a PR
touches it:

```yaml
- uses: actions/checkout@v4
- uses: viethoang35/architecture-workbench@main
  with:
    args: 'validate examples/my-project'
```

`--repo-root` is set to the checked-out workspace automatically, so relative example paths resolve
against your repository, not this action's own image. `args` is passed straight to the `awb` CLI —
anything you'd run locally works here, including LLM-backed steps if you supply credentials via
`env:` on the step:

```yaml
- uses: viethoang35/architecture-workbench@main
  with:
    args: 'generate examples/my-project --step review --provider openrouter --model deepseek/deepseek-v4-flash'
  env:
    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
```

---

# 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](#example-projects) above)
* A multi-arch (`linux/amd64`/`linux/arm64`) Docker image — no local Python setup required
* Published on PyPI (`pip install architecture-workbench`) and usable as a GitHub Action against
  your own repository's CI
* 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.
