Contributing to Cloudwright

March 26, 2026 · View on GitHub

Development Setup

git clone https://github.com/xmpuspus/cloudwright.git
cd cloudwright
pip install -e packages/core -e packages/cli -e packages/web
pip install pytest pytest-timeout ruff

Running Tests

# All tests
pytest

# Core only
pytest packages/core/tests/ -x -q

# Web API tests
pytest packages/web/tests/ -x -q

# CLI tests
pytest packages/cli/tests/ -x -q

# MCP tests
pytest packages/mcp/tests/ -x -q

# Frontend unit tests (requires npm install in packages/web/frontend/)
cd packages/web/frontend && npx vitest run

# With coverage
pytest --cov=cloudwright --cov-report=term-missing

Linting

ruff check packages/
ruff format packages/

Project Structure

packages/
  core/     cloudwright         Core library
    cloudwright/
      prompts.py              Prompt constants and service catalogs
      session.py              ConversationSession (multi-turn chat)
      designer.py             Architect (single-shot design + template matching)
      parsing.py              JSON extraction and ArchSpec parsing
      spec.py                 ArchSpec model and related types
      cost.py                 Cost engine
      validator.py            Compliance validation
      security.py             Security scanner
      differ.py               Spec diffing
      linter.py               Anti-pattern detection
      session_store.py        File-based session persistence
      exporter/               12 export formats
        terraform/            Per-provider HCL generation (aws.py, gcp.py, azure.py, databricks.py)
      catalog/                Service catalog and pricing
  cli/      cloudwright-cli     Typer CLI with Rich formatting
    cloudwright_cli/
      commands/
        chat.py               Entry point (arg parsing)
        chat_ui.py            Rich Live terminal UI
        chat_session.py       Session lifecycle
        chat_streaming.py     Stream consumer
      decorators.py           Command output/error wrapper
  web/      cloudwright-web     FastAPI backend + React frontend
    cloudwright_web/
      app.py                  App factory (create_app)
      middleware.py           Rate limiter, path guard, API key auth
      singletons.py           Thread-safe service factories
      streaming.py            Shared SSE helper
      routers/                Per-domain endpoint modules
    frontend/                 React + Vite + Zustand
  mcp/      cloudwright-mcp     MCP server bridge

Where to Add Things

  • New prompts or service keys: packages/core/cloudwright/prompts.py
  • New cloud provider (terraform): packages/core/cloudwright/exporter/terraform/{provider}.py
  • New export format: packages/core/cloudwright/exporter/{format}.py + register in __init__.py
  • New web endpoint: packages/web/cloudwright_web/routers/{domain}.py + mount in app.py
  • New CLI command: packages/cli/cloudwright_cli/commands/{cmd}.py + register in main.py

Pull Requests

  • Create a feature branch from main
  • Write tests for new functionality
  • Run ruff check and pytest before submitting
  • Keep PRs focused on a single change
  • Update CHANGELOG.md for user-facing changes

Architecture

Everything flows through ArchSpec — the central Pydantic model. The design pipeline:

  1. User describes architecture in natural language
  2. Architect (designer.py) calls LLM to generate an ArchSpec
  3. CostEngine prices it from Catalog data
  4. Validator checks compliance
  5. Exporters turn it into Terraform, CloudFormation, diagrams

ConversationSession (session.py) wraps multi-turn conversations with history tracking, streaming, cost tracking, and session persistence.