cloudwright-ai 0.2.3

Architecture intelligence for cloud engineers — design, cost, compare, export

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.

"HIPAA-compliant 3-tier app on AWS, budget $3k/month"
    │
    ▼
┌────────────────────────────────────────────────┐
│  ArchSpec (YAML)                               │
│  ├── 8 components (ALB, ECS, RDS, S3, ...)    │
│  ├── connections with protocols                │
│  └── constraints: hipaa, budget: 3000          │
└────────┬───────────┬──────────┬────────────────┘
         │           │          │
    ┌────▼───┐  ┌───▼────┐ ┌──▼──────────┐
    │  Cost  │  │Validate│ │   Export     │
    │$2,847  │  │ HIPAA  │ │ Terraform   │
    │  /mo   │  │ 5/5    │ │ CFN, Mermaid│
    └────────┘  └────────┘ └─────────────┘

Why Cloudwright

Most cloud tooling assumes you already know what to build (IaC) or already have it deployed (cost dashboards, security scanners). Cloudwright operates in the design phase — the gap where architects currently rely on tribal knowledge, ad-hoc spreadsheets, and copy-pasting last quarter's Terraform.

One spec, many outputs. ArchSpec is the universal interchange format. Every module — design, cost, compliance, export, diff, lint, score — reads and writes it. No glue code, no format conversion.

How it compares

Capability	Cloudwright	Terraform	Pulumi Neo	Brainboard	Infracost	Checkov
NL to architecture	Y	-	Y	Y	-	-
IaC generation	TF + CFN	HCL	Code	TF	-	-
Cost estimation	Y (design-time)	-	-	Basic	Y (code-time)	-
Compliance validation	6 frameworks	-	OPA policies	-	-	2500+ rules
Architecture diffing	Y	Plan diff	Preview diff	Drift	Cost diff	-
Diagram export	Mermaid + D2	-	-	Y	-	-
SBOM / AIBOM	Y	-	-	-	-	-
Multi-cloud	AWS/GCP/Azure	All	All	AWS/GCP/Azure/OCI	AWS/GCP/Azure	All
Open source	Y	BSL / OpenTofu	Engine only	-	CLI only	Y
Runs locally	Y	Y	Y	-	Y	Y

Terraform and Infracost are deployment/cost tools that sit downstream — Cloudwright generates the Terraform code and estimates costs before any code exists. Checkov and Prowler scan after code is written; Cloudwright validates at design time. Brainboard is the closest direct competitor (NL-to-arch + TF), but it's SaaS-only and doesn't do compliance or cost estimation.

Full competitor analysis covering 30 tools across IaC, cost, compliance, and diagramming: competitor-landscape.md

Quick Start

pip install cloudwright[cli]

Set an LLM provider key:

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
cloudwright cost spec.yaml

# 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

# Interactive multi-turn design
cloudwright chat

Features

Architecture Design

LLM-powered architecture generation from plain English. Supports multi-turn conversation, constraint-aware design, and natural language modification of existing specs.

cloudwright design "Serverless data pipeline on GCP with Pub/Sub, Dataflow, and BigQuery" \
  --provider gcp --budget 2000 --compliance gdpr

cloudwright modify spec.yaml "Add a Redis cache between the API and database"

cloudwright chat  # interactive mode with /save, /cost, /export commands

100 service keys across three clouds:

• AWS (47): EC2, ECS, EKS, Lambda, RDS, Aurora, DynamoDB, S3, SQS, SNS, Kinesis, Redshift, SageMaker, KMS, GuardDuty, CloudTrail, and more
• GCP (25): Compute Engine, GKE, Cloud Run, Cloud SQL, Spanner, BigQuery, Pub/Sub, Vertex AI, Cloud Build, and more
• Azure (28): Virtual Machines, AKS, Azure Functions, Azure SQL, Cosmos DB, Synapse, Azure ML, Azure Sentinel, and more

The architect applies safe defaults automatically: encryption on data stores, backups on databases, multi-AZ on production workloads, auto-scaling on compute.

Cost Estimation

Per-component monthly pricing from a built-in SQLite catalog. No external API calls, no rate limits. Supports four pricing tiers.

cloudwright cost spec.yaml                              # on-demand pricing
cloudwright cost spec.yaml --pricing-tier reserved_1yr  # 1-year reserved
cloudwright cost spec.yaml --compare gcp,azure          # multi-cloud comparison

The cost engine resolves prices through three tiers: catalog database (instance-level pricing), registry formula dispatch (10 named formulas for serverless/managed services), and static fallback table (90+ service defaults). Data transfer costs are calculated separately with per-provider egress rates.

Pricing tiers: on_demand (1.0x), reserved_1yr (0.6x), reserved_3yr (0.4x), spot (0.3x).

Compliance Validation

Six compliance frameworks with 35 individual checks:

Framework	Checks	Key Validations
HIPAA	5	Encryption at rest/transit, audit logging, access control, BAA eligibility
PCI-DSS	5	WAF, network segmentation, encryption, TLS 1.2+, audit trail
SOC 2	5	Logging, access controls, encryption, availability, change management
FedRAMP Moderate	7	FIPS 140-2, US regions, MFA, audit logging, continuous monitoring
GDPR	6	EU data residency, encryption, access controls, audit trail, data deletion
Well-Architected	7	Multi-AZ, auto-scaling, backup, monitoring, SPOF detection, cost optimization

cloudwright validate spec.yaml --compliance hipaa,pci-dss,soc2
cloudwright validate spec.yaml --well-architected
cloudwright validate spec.yaml --compliance fedramp --report audit-report.md

Exit code 1 on failures, making it CI-friendly.

Infrastructure Export

Seven export formats from a single ArchSpec:

Format	Flag	Description
Terraform HCL	terraform	Provider-native resources for AWS (24 types), GCP (11), Azure (10)
CloudFormation	cloudformation	YAML template with Parameters and Outputs
Mermaid	mermaid	Tier-grouped flowchart for docs and GitHub
D2	d2	D2 diagram language with provider badges
CycloneDX SBOM	sbom	CycloneDX 1.5 service bill of materials
OWASP AIBOM	aibom	AI bill of materials documenting LLM usage and risks
Compliance Report	compliance	Audit-ready markdown with check details and evidence

cloudwright export spec.yaml --format terraform -o ./infra
cloudwright export spec.yaml --format mermaid
cloudwright export spec.yaml --format sbom -o sbom.json

Terraform output uses variables for sensitive values (no hardcoded passwords or ARNs), includes provider blocks with region configuration, and generates data sources for VPC/subnet discovery.

Architecture Diffing

Structured comparison between two ArchSpec versions with component-level changes, cost delta, and compliance impact assessment.

cloudwright diff v1.yaml v2.yaml

Detects: added/removed components, changed configurations, connection changes (added/removed/modified), cost impact, and security implications (removal of WAF, encryption changes, auth service changes).

Multi-Cloud Comparison

Maps equivalent services across providers using 22 cross-cloud equivalence pairs:

ec2 <-> compute_engine <-> virtual_machines
rds <-> cloud_sql <-> azure_sql
s3  <-> cloud_storage <-> blob_storage
eks <-> gke <-> aks
...

cloudwright compare spec.yaml --providers gcp,azure

Shows side-by-side service mapping with monthly cost totals per provider.

Architecture Linter

10 anti-pattern checks:

cloudwright lint spec.yaml
cloudwright lint spec.yaml --strict  # fail on warnings too

Errors: unencrypted data stores, single-AZ databases, missing load balancer, public databases, single point of failure. Warnings: oversized instances (16xlarge+), missing WAF, missing monitoring, missing backups, missing auth.

Architecture Scorer

Five-dimension quality scoring (0-100, letter grade):

cloudwright score spec.yaml --with-cost

• Reliability (30%): load balancing, multi-AZ, auto-scaling, CDN, caching
• Security (25%): WAF, auth, encryption, HTTPS, DNS management
• Cost Efficiency (20%): budget compliance, per-component ratio, free tier usage
• Compliance (15%): framework validation score
• Complexity (10%): component count, connection density, tier separation

Grades: A (90+), B (80+), C (70+), D (60+), F (<60).

Blast Radius Analysis

Dependency graph analysis with SPOF detection and critical path identification.

cloudwright analyze spec.yaml
cloudwright analyze spec.yaml --component api_gateway  # focus on one component

For each component: direct dependents, transitive dependents, blast radius, SPOF status, and tier position.

Drift Detection

Compares architecture spec against deployed infrastructure.

cloudwright drift spec.yaml terraform.tfstate
cloudwright drift spec.yaml cloudformation-template.yaml

Produces a drift score (0.0-1.0) with lists of drifted, extra, and missing components.

Policy Engine

Policy-as-code via YAML rules. Nine built-in checks: max_components, all_encrypted, require_multi_az, budget_monthly, no_banned_services, required_tags, min_redundancy, allowed_providers, allowed_regions.

# policy.yaml
rules:
  - name: enforce-encryption
    check: all_encrypted
    severity: deny
  - name: budget-cap
    check: budget_monthly
    value: 10000
    severity: deny
  - name: no-azure
    check: allowed_providers
    value: [aws, gcp]
    severity: warn

cloudwright policy spec.yaml --rules policy.yaml

Severity levels: deny (exit code 1), warn, info.

Infrastructure Import

Import existing infrastructure into ArchSpec format:

cloudwright import terraform.tfstate -o spec.yaml
cloudwright import cloudformation-template.yaml -o spec.yaml

Auto-detects format from file extension and content. Plugin support for custom importers via the cloudwright.importers entry point.

Templates

14 starter architectures across three providers:

cloudwright init --list                              # show available templates
cloudwright init --template serverless_api           # AWS API Gateway + Lambda + DynamoDB
cloudwright init --template gcp_microservices -o .   # GKE + service mesh
cloudwright init --project                           # create .cloudwright/ project directory

AWS (8): three_tier_web, serverless_api, ml_pipeline, data_lake, event_driven, static_site, microservices, batch_processing. GCP (3): three_tier_web, serverless_api, microservices. Azure (3): three_tier_web, serverless_api, microservices.

Web UI

FastAPI backend + React frontend for browser-based architecture design.

pip install cloudwright[web]
cloudwright chat --web

10 API endpoints: design, modify, cost, validate, export, diff, catalog search, catalog compare, chat, health.

Plugin System

Four extension points via Python entry points:

• cloudwright.exporters — custom export formats
• cloudwright.validators — custom compliance frameworks
• cloudwright.policies — custom policy checks
• cloudwright.importers — custom infrastructure importers

cloudwright --list-plugins  # discover installed plugins

ArchSpec Format

ArchSpec is plain YAML, human-editable, and version-controllable alongside code.

name: healthcare-portal
version: 1
provider: aws
region: us-east-1

constraints:
  compliance: [hipaa]
  budget_monthly: 5000
  availability: 99.9

components:
  - id: alb
    service: alb
    provider: aws
    label: Application Load Balancer
    tier: 1

  - id: api
    service: ecs
    provider: aws
    label: API Service
    tier: 2
    config:
      launch_type: FARGATE
      cpu: 512
      memory: 1024
      desired_count: 2

  - id: db
    service: rds
    provider: aws
    label: PostgreSQL
    tier: 3
    config:
      engine: postgresql
      instance_class: db.r5.large
      multi_az: true
      encryption: true
      storage_gb: 100

connections:
  - source: alb
    target: api
    protocol: https
    port: 443
  - source: api
    target: db
    protocol: tcp
    port: 5432

Components use a 5-tier system for vertical positioning: Edge (0), Ingress (1), Compute (2), Data (3), Storage/Analytics (4).

CLI Reference

Command	Description
design <prompt>	Generate ArchSpec from natural language
modify <spec> <instruction>	Modify existing spec with natural language
cost <spec>	Monthly cost breakdown with optional --compare, --pricing-tier
compare <spec>	Multi-cloud service mapping and cost comparison
validate <spec>	Compliance checks with --compliance, --well-architected, --report
export <spec>	Export to IaC/diagram/SBOM with --format, --output
diff <spec_a> <spec_b>	Structured diff with cost delta and compliance impact
import <source>	Import from Terraform state or CloudFormation
chat	Interactive multi-turn design session (--web for browser UI)
init	Initialize from template with --template, --project
lint <spec>	Anti-pattern detection (--strict fails on warnings)
score <spec>	Quality scoring across 5 dimensions (--with-cost)
analyze <spec>	Blast radius and SPOF detection (--component for focus)
drift <spec> <infra>	Compare design vs deployed infrastructure
policy <spec>	Evaluate policy rules from YAML (--rules)
refresh	Update catalog pricing data (--provider, --dry-run)
catalog search <query>	Search instance catalog by specs
catalog compare <a> <b>	Side-by-side instance comparison

Global flags: --json, --verbose / -v, --version / -V.

Python API

from pathlib import Path
from cloudwright import ArchSpec
from cloudwright.cost import CostEngine
from cloudwright.validator import Validator
from cloudwright.exporter import export_spec
from cloudwright.differ import diff_specs
from cloudwright.linter import lint
from cloudwright.scorer import Scorer

spec = ArchSpec.from_file("spec.yaml")

# Cost
engine = CostEngine()
priced = engine.price(spec)
for item in priced.cost_estimate.breakdown:
    print(f"{item.component_id}: ${item.monthly:,.2f}/mo")

# Compliance
validator = Validator()
results = validator.validate(spec, compliance=["hipaa", "pci-dss"])

# Export
hcl = export_spec(spec, "terraform", output_dir="./infra")
diagram = export_spec(spec, "mermaid")

# Diff
old = ArchSpec.from_file("v1.yaml")
new = ArchSpec.from_file("v2.yaml")
diff = diff_specs(old, new)

# Lint
findings = lint(spec)

# Score
scorer = Scorer()
report = scorer.score(spec)
print(f"Grade: {report.grade} ({report.overall:.0f}/100)")

Service Catalog

Ships as a SQLite database bundled with the package. No network calls required.

• Compute, database, networking, and storage pricing for AWS, GCP, and Azure
• 4 pricing tiers (on-demand, reserved 1yr/3yr, spot)
• Cross-cloud instance equivalences with confidence scores
• 22 service-level equivalence pairs for multi-cloud mapping
• 10 named pricing formulas for managed/serverless services
• 90+ static fallback prices for less common services

cloudwright catalog search "8 vcpu 32gb memory"
cloudwright catalog compare m5.xlarge n2-standard-4 Standard_D4s_v5

Benchmarks

Evaluated against raw Claude (Sonnet 4.6) across 54 use cases spanning greenfield, compliance, cost optimization, import, microservices, data pipelines, industry-specific, migration, edge computing, and cross-cloud comparison scenarios.

Metric	Cloudwright	Claude (raw)	Delta
Structural Validity	79.6%	37.0%	+42.6
Compliance Completeness	62.9%	38.5%	+24.3
Export Quality (IaC)	55.7%	0.3%	+55.5
Diff Capability	100.0%	0.0%	+100.0
Reproducibility	77.9%	35.0%	+42.9
Time to IaC	82.5%	0.0%	+82.5
Overall	68.1%	28.0%	+40.1

Cloudwright wins 6 of 8 metrics. Weakest areas (active development): cost accuracy and service correctness on import/migration use cases.

Full results: benchmark/results/benchmark_report.md

Repository Structure

cloudwright/
  packages/
    core/       pip install cloudwright          Models, architect, catalog, cost, validators, exporters
    cli/        pip install cloudwright[cli]     Typer CLI with Rich formatting
    web/        pip install cloudwright[web]     FastAPI + React web UI
  catalog/                                      Service catalog JSON (compute, database, storage, networking)
  benchmark/                                    54 use cases + evaluation framework

Development

git clone https://github.com/theAtticAI/cloudwright
pip install -e packages/core
pip install -e packages/cli
pip install -e packages/web

pytest packages/core/tests/           # 689 tests
ruff check packages/ && ruff format packages/

LLM-dependent tests (architect, chat) require an API key and are skipped by default:

ANTHROPIC_API_KEY=sk-ant-... pytest packages/core/tests/test_architect.py -v

License

MIT