cloudwright

# Cloudwright

*Describe a cloud architecture in English. Get Terraform, costs, and a compliance check.*

[![PyPI](https://img.shields.io/pypi/v/cloudwright-ai.svg)](https://pypi.org/project/cloudwright-ai/)
[![CI](https://github.com/xmpuspus/cloudwright/actions/workflows/ci.yml/badge.svg)](https://github.com/xmpuspus/cloudwright/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/pypi/pyversions/cloudwright-ai)](https://pypi.org/project/cloudwright-ai/)
[![xmpuspus/cloudwright MCP server](https://glama.ai/mcp/servers/xmpuspus/cloudwright/badges/score.svg)](https://glama.ai/mcp/servers/xmpuspus/cloudwright)

<p align="center">
  <img src="examples/cloudwright-hero.gif" alt="Cloudwright: prompt to spec, cost, compliance, Terraform" width="800">
</p>

<p align="center"><em>Prompt to spec, cost breakdown, compliance check, and Terraform in one pass.</em></p>

```bash
pip install 'cloudwright-ai[cli]'
export ANTHROPIC_API_KEY=sk-ant-...
cloudwright design "HIPAA healthcare API on AWS with Postgres and Redis"
```

Cloudwright takes a one-line description of a cloud system and produces a structured architecture spec, a per-component cost breakdown, a compliance report, and ready-to-apply Terraform, Pulumi (TypeScript or Python), or CloudFormation. It works across AWS, GCP, Azure, and Databricks. The latest work adds compliance scanning that maps every finding to the framework control it violates (HIPAA / SOC 2 / FedRAMP / PCI-DSS / ISO 27001 / NIST), a `cloudwright plan` step that proves the exported infrastructure actually deploys, and live import for GCP and Azure alongside AWS.

[Try it](#quickstart) - [What's new](#whats-new) - [Docs](docs/) - [MCP server](#mcp-server-claude--cursor--cline)

## What you get

- Architecture spec (typed YAML, version-controlled, the single source of truth)
- Cost breakdown across AWS, GCP, Azure, Databricks (region-aware, per-component, four pricing tiers, optional carbon + FOCUS CSV export). Each line carries a confidence flag — `high` from the bundled price catalog (deepest on AWS), `low` from formula/fallback — so an estimate never silently passes off a guess as a quote.
- Compliance report covering HIPAA, SOC 2, PCI-DSS, FedRAMP Moderate, GDPR, NIST 800-53, and Well-Architected, with OSCAL 1.1.2 export and control traceability
- Terraform, OpenTofu, Pulumi (TypeScript or Python), and CloudFormation export with safe defaults (encryption, IMDSv2, locked-down S3, sensible RDS settings)
- Diagrams in ASCII, Mermaid, D2, and a fully editable web canvas
- MCP server for AI agents (Claude Desktop, Cursor, Cline, and any MCP-compatible client)

## Quickstart

```bash
cloudwright design "HIPAA healthcare API on AWS with Postgres and Redis"
cloudwright cost spec.yaml --workload-profile medium
cloudwright validate spec.yaml --compliance hipaa,soc2
cloudwright export spec.yaml --format terraform -o ./infra
cloudwright chat --web                                # browser canvas at http://localhost:8765
```

All commands except `design`, `modify`, `chat`, and `adr` work fully offline. Set `ANTHROPIC_API_KEY` (preferred) or `OPENAI_API_KEY` to enable the LLM-powered ones. Drop `--json` on any command for machine-readable output.

## Smart Canvas + Module Catalog (v1.2)

<p align="center">
  <img src="examples/cloudwright-smart-canvas-demo.gif" alt="Cloudwright Smart Canvas" width="800">
</p>

<p align="center"><em>Drag-and-drop canvas with per-provider resource catalog, approved modules, and standards checks.</em></p>

The web diagram is a fully editable architecture canvas. Edits (add, drag, connect, edit fields, delete) are deterministic frontend mutations, so they are instant, free, and reproducible. They do not call the LLM.

A left-side **Catalog drawer** has three tabs:

- **Resources** - the full catalog for the active provider, served by `/api/catalog/services` (case-insensitive `?provider=`).
- **Modules** - approved multi-resource patterns from `/api/modules`. Bundled: AWS Three-Tier Web, AWS Serverless API, AWS Data Lake, GCP Serverless API, Azure Three-Tier Web.
- **Standards** - runs `POST /api/canvas/validate` and surfaces orphan connections, partial modules, unapproved modules, naming-prefix violations, and missing required tags.

When a module instance is intact, the Terraform exporter emits a single `module "<id>"` block with the catalog's pinned `source` and `version`. Modified modules fall back to per-component resource rendering. Mixed specs work: catalog modules render as modules, ad-hoc resources as resources, side by side.

```bash
cloudwright chat --web
# Open http://localhost:8765, use the Catalog drawer, then Export -> Terraform
```

## MCP server (Claude / Cursor / Cline)

Expose Cloudwright as [Model Context Protocol](https://modelcontextprotocol.io/) tools so AI agents can design, cost, validate, and export architectures directly. 18 tools across 6 groups (design, cost, validate, analyze, export, session).

```bash
pip install cloudwright-ai-mcp
cloudwright mcp                              # all tools, stdio
cloudwright mcp --tools design,cost          # subset
cloudwright mcp --transport sse              # SSE for HTTP clients
```

`claude_desktop_config.json` (same shape works for Cursor and Cline):

```json
{
  "mcpServers": {
    "cloudwright": {
      "command": "cloudwright",
      "args": ["mcp"]
    }
  }
}
```

## Analysis

`cloudwright lint` (10 anti-pattern checks), `cloudwright score` (5-dimension quality grade), `cloudwright analyze` (blast radius and SPOF), `cloudwright drift <spec> <tfstate>` (design vs deployed), `cloudwright policy --rules policy.yaml` (policy-as-code with 9 built-in checks), `cloudwright security` (security anti-patterns; also scans exported Terraform HCL), `cloudwright compliance <spec> --frameworks hipaa,soc2,fedramp` (every finding mapped to its HIPAA / SOC 2 / FedRAMP / PCI-DSS / ISO 27001 / NIST control ID, with optional Checkov deep scan), and `cloudwright plan <spec> --target terraform` (proves the exported artifact validates / plans). Every command supports `--json`. See [docs/](docs/) and the `examples/` directory for end-to-end samples.

## Python API

```python
from cloudwright import ArchSpec
from cloudwright.cost import CostEngine
from cloudwright.validator import Validator
from cloudwright.exporter import export_spec

spec = ArchSpec.from_file("spec.yaml")
priced = CostEngine().estimate(spec, workload_profile="medium")
results = Validator().validate(spec, compliance=["hipaa", "pci-dss"])
hcl = export_spec(spec, "terraform", output_dir="./infra")
```

<a id="whats-new"></a>

## What's new in v1.6.0

<p align="center">
  <img src="examples/cloudwright-review-demo.gif" alt="cloudwright review gives an offline, severity-ranked architecture critique; cloudwright compliance --oscal emits an OSCAL component-definition" width="900">
</p>

<p align="center"><em>`cloudwright review` — offline scorer + linter + validator in one report — then the same findings exported as OSCAL.</em></p>

The design engine now reviews and repairs its own output, compliance binds at design time with OSCAL output, and the cost estimate stops guessing silently.

- **The architect self-corrects.** Every `cloudwright design` runs the built-in critics (scorer, linter, validator) against the generated spec and, when blocking findings remain, repairs it in one bounded pass before you ever see it — recorded in `spec.metadata.critique`. The same engine is a free, offline command: `cloudwright review spec.yaml` gives a severity-ranked architecture review with no API key.
- **OSCAL + control traceability.** `cloudwright compliance spec.yaml --frameworks fedramp --oscal` emits an OSCAL 1.1.2 component-definition — control mapping a CSPM or evidence tool cannot produce before deploy. `--traceability` prints the chain design intent -> component -> Terraform resource -> control ID -> status.
- **Cost you can defend.** Region-aware pricing (every region used to be priced as us-east-1), data-transfer/egress estimation, a per-line pricing confidence (`high` = catalog, `low` = fallback), design-time carbon (`cloudwright cost --carbon`), and FOCUS-spec CSV export (`--focus`).
- **Drift -> remediation and OpenTofu.** `cloudwright drift ... --remediate` turns drift into a cost + compliance + plan preview (read-only). `cloudwright export --format opentofu` and a tofu-aware `plan`.
- **Hardening.** Terraform exporter injection hardening, `cloudwright plan` no longer carries the LLM key into the IaC subprocess, the WAF export is deployable, and the "compliance overrides workload profile" guarantee is now actually enforced for sandbox specs.

```bash
cloudwright review spec.yaml                                   # offline, no API key
cloudwright compliance spec.yaml --frameworks fedramp --oscal  # OSCAL component-definition
cloudwright cost spec.yaml --carbon --focus                    # region-aware + carbon + FOCUS CSV
cloudwright export spec.yaml --format opentofu -o ./infra
```

See [docs/](docs/) for getting-started, CLI, MCP, and troubleshooting guides.

## What's new in v1.5.0

Terminal — `cloudwright compliance` maps every finding to its framework control ID, then `cloudwright plan` proves the Terraform validates:

<p align="center">
  <img src="examples/cloudwright-controls-demo.gif" alt="cloudwright compliance maps each finding to HIPAA/SOC2/FedRAMP control IDs, then cloudwright plan proves the Terraform validates" width="900">
</p>

Web canvas — the same checks as Compliance and Plan tabs:

<p align="center">
  <img src="examples/cloudwright-controls-web-demo.gif" alt="Compliance and Plan tabs in the web canvas: control-mapped findings and a DEPLOYABLE verdict" width="900">
</p>

<table>
  <tr>
    <td width="50%"><img src="docs/screenshots/cloudwright-compliance-tab.png" alt="Compliance tab: per-framework posture table with controls satisfied/violated, scanner built