Cloudwright

Architecture intelligence for cloud engineers.

Cloudwright bridges the gap between a whiteboard sketch and deployable infrastructure. Describe a system in natural language, and Cloudwright produces a structured architecture spec, cost estimates, compliance reports, Terraform/CloudFormation code, diagrams, and diffs — all from a single format called ArchSpec.

<p align="center"> <img src="examples/cloudwright-demo.gif" alt="Cloudwright CLI Demo" width="800"> </p> <p align="center"><em>HIPAA-compliant healthcare API on AWS — 12 components with VPC boundaries, cost breakdown ($2,263/mo), compliance validation (HIPAA 60%), and eight export formats including Terraform, CloudFormation, and ASCII architecture diagrams.</em></p>

| Architecture Diagram | Cost Breakdown | |:---:|:---:| | | | | | |

<p align="center"><em>Web UI — interactive React Flow diagrams with tier-based layout, service-category color coding, boundary grouping, per-component cost overlay, and compliance validation.</em></p>

Installation

pip install 'cloudwright-ai[cli]'          # CLI
pip install 'cloudwright-ai[web]'          # CLI + Web UI
pip install cloudwright-ai-mcp             # MCP server for AI agents

Set an LLM provider key (required for design, modify, chat, adr; all other commands work offline):

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

# Design from natural language
cloudwright design "3-tier web app on AWS with Redis and PostgreSQL"

# Estimate cost with production-realistic workload profiles
cloudwright cost spec.yaml --workload-profile medium
cloudwright cost spec.yaml -w enterprise --pricing-tier reserved_1yr

# Validate compliance
cloudwright validate spec.yaml --compliance hipaa,soc2

# Export Terraform
cloudwright export spec.yaml --format terraform -o ./infra

# Compare cost across clouds
cloudwright cost spec.yaml --compare gcp,azure

# Security scan
cloudwright security spec.yaml

# Import existing infrastructure
cloudwright import terraform.tfstate -o spec.yaml

# Interactive multi-turn design
cloudwright chat           # terminal
cloudwright chat --web     # browser UI

---

What's New

v1.0.0 — Production-Ready Architecture (2026-03-26)

<p align="center"> <img src="examples/cloudwright-v100-demo.gif" alt="Cloudwright v1.0 Web UI Demo" width="720"> </p> <p align="center"><em>v1.0 Web UI -- HIPAA-compliant 3-tier design with real-time cost estimation ($1,534/mo), compliance validation, and architecture diagram.</em></p>

The 1.0 release is a ground-up restructuring of the entire codebase. Every major module has been decomposed for maintainability, testability, and extensibility.

Core decomposition. The 1,491-line architect.py monolith is split into four focused modules: session.py (multi-turn conversation), designer.py (single-shot design + template matching), parsing.py (JSON extraction, service normalization), and prompts.py (all LLM prompt constants). Existing from cloudwright.architect import ... imports still work via a backward-compat shim.

Web backend. All 19 endpoints moved from a single 720-line app.py into 9 FastAPI router modules with shared middleware, singletons, and a unified SSE streaming abstraction. Each router is independently testable.

Terraform exporter. Split from one 1,161-line file into per-provider modules (aws.py, gcp.py, azure.py, databricks.py). Adding a new cloud provider is now a single file.

CLI. The monolithic chat command decomposed into UI, session lifecycle, and streaming layers. New @cloudwright_command decorator eliminates 10+ lines of boilerplate per command.

Security and correctness (v0.5.0). Connection validation rejects orphan references. Config sanitization blocks shell metacharacters in Terraform/CloudFormation export. Template match confidence scores (0.0-1.0). Explicit BaseLLM.pricing property replaces fragile string-matching. Error hints capped to sliding window of 5. MCP sessions persist to disk.

1,031 tests across all packages, all passing.

v0.4.0 -- Security Hardening and Export Enhancements (2026-03-20)

<p align="center"> <img src="examples/cloudwright-v040-demo.gif" alt="Cloudwright v0.4.0 Web UI Demo" width="720"> </p> <p align="center"><em>Web UI -- interactive architecture design with LLM-generated suggestions, FedRAMP/GDPR validation, SVG/PNG export, and self-contained HTML reports.</em></p>

Security hardening, structured logging, and new export capabilities across all packages.

Security. SessionStore path traversal guard, optional API key auth (CLOUDWRIGHT_API_KEY), rate limiting on all streaming endpoints, LLM empty response handling, MCP session thread safety. Silent except: pass patterns replaced with logged warnings.

HTML Report export. New --format html produces a self-contained, shareable HTML file with embedded Mermaid diagram, cost breakdown, component inventory, and compliance summary. Opens in any browser, shareable via email/Slack/Gist.

cloudwright export spec.yaml --format html -o report.html

Web UI improvements. FedRAMP and GDPR added to validation panel (all 6 frameworks now available). SVG/PNG diagram export buttons wired. Modify tab now uses SSE streaming. LLM-generated suggestion buttons replace static fallback list. CORS origins configurable via CLOUDWRIGHT_CORS_ORIGINS.

<p align="center"> <img src="examples/cloudwright-v040-demo.gif" alt="Cloudwright v0.4.0 Web UI Demo" width="720"> </p> <p align="center"><em>Web UI - interactive architecture design with LLM-generated suggestions, HIPAA validation with severity scoring, and 6 compliance frameworks including FedRAMP and GDPR.</em></p>

Observability. Structured logging with structlog (JSON or console output via CLOUDWRIGHT_LOG_FORMAT). LLM call timing instrumentation. Rate limit hits logged.

Attribution. All exported diagrams and IaC now include "Designed with Cloudwright" attribution with project URL.

Also added: .env.example for easy setup, CHANGELOG.md with full version history, CI coverage reporting, action version alignment.

1,202 tests (973 core + 121 web + 99 CLI + 9 MCP), all passing with zero skips.

v0.3.5 — Conversational UX and Observability (2026-03-14)

<p align="center"> <img src="examples/cloudwright-v035-demo.gif" alt="Cloudwright v0.3.5 Web UI Demo" width="720"> </p> <p align="center"><em>Web UI — natural language design with streaming SSE, suggestion buttons, cost estimation, architecture diagram with tier boundaries, and multi-turn modification via suggestions.</em></p>

Major upgrade to the conversational experience across CLI, Web, and MCP. Token-level streaming, session persistence, usage tracking, and structured error handling.

Streaming. Token-level streaming in CLI (Rich Live display) and Web (SSE /api/chat/stream). Responses render incrementally instead of blocking until complete.

Session persistence. Save and resume conversations across sessions. CLI: /save-session, /load-session, /sessions, --resume SESSION_ID. SDK: SessionStore class with save(), load(), list_sessions(), delete().

Usage tracking. Per-turn and cumulative token counts with cost estimation. Displayed after every response in CLI, included in API responses and SSE done events.

cloudwright chat                    # streaming by default
cloudwright chat --resume my-sess   # resume saved session
cloudwright chat --debug            # show prompts, timing, token counts

Also added:

• Context window management — automatic history trimming at 50 turns
• Spec diff display after modifications (added/removed/changed components)
• Clarification routing for ambiguous single-word inputs
• Rate limiting (30 req/min per IP) and structured error responses in Web API
• Thread-safe singletons for web server concurrency
• Suggestion buttons and confirmation dialogs in React frontend
• MCP session TTL (1hr), max 100 sessions, auto-cleanup
• Expanded LLM retry logic with jitter (rate limit, connection, 5xx, timeout)
• Per-call timeout parameter on all LLM methods
• Few-shot examples in system prompts to reduce JSON parsing failures
• 44 Playwright browser tests covering every README feature (design, cost, validate, export, spec, modify, suggestions, multi-turn, streaming, confirmation dialogs, API endpoints)
• 1,144 tests total (1,084 unit/integration + 28 e2e/behavioral + 44 browser, all with real LLM)

v0.3.3 — Cost Accuracy and Import Reliability (2026-03-09)

Workload profiles fix cost estimates that were 10-100x too low for production workloads. Profiles inject realistic sizing defaults (Lambda invocations, DB storage, cache memory, CDN egress) before pricing formulas run — without overwriting explicit config.

cloudwright cost spec.yaml -w medium       # 1M Lambda requests, 100GB DB, 6GB cache
cloudwright cost spec.yaml -w enterprise   # 100M requests, 2TB DB, 26GB cache

| Profile | Lambda Requests | DB Storage | Cache Memory | CDN Egress | EKS Nodes | |---|---|---|---|---|---| | small | 100K/mo | 20 GB | 1 GB | 10 GB | 2 | | medium | 1M/mo | 100 GB | 6 GB | 100 GB | 3 | | large | 10M