Metadata-Version: 2.4
Name: infra-designer
Version: 0.1.0
Summary: Plan, deploy, and audit cloud infrastructure from a single reproducible spec — compiles declarative components to plain Terraform.
Author: Alex Kang
License: MIT
Project-URL: Homepage, https://github.com/AlexK020908/infra-designer
Project-URL: Repository, https://github.com/AlexK020908/infra-designer
Project-URL: Issues, https://github.com/AlexK020908/infra-designer/issues
Keywords: infrastructure,terraform,aws,iac,devops,claude,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# infra-designer

**Plan, deploy, and audit cloud infrastructure from a single reproducible spec —
right inside your coding agent.**

Describe the app you want to build; infra-designer interviews you for the requirements
that actually pick and size components, designs a right-sized architecture, and writes a
canonical `spec.json` into your repo. From that one spec it deterministically generates
**plain Terraform** (or idempotent shell scripts), an **architecture diagram**, and a
**drift audit** — all output you own, no lock-in.

It's harness-agnostic: the same engine and instructions run in **Claude Code, Codex,
Cursor, or anything that speaks MCP**.

```mermaid
flowchart LR
  req["your requirements"] --> spec["infra/&lt;project&gt;/spec.json<br/>(source of truth)"]
  spec --> tf["Terraform / deploy.sh"]
  spec --> dia["diagram (drawio + mermaid)"]
  spec --> aud["drift audit"]
```

It right-sizes the stack instead of defaulting to heavyweight AWS: a simple app gets a
**Vercel + Supabase** design; a photo-sharing app at scale gets ALB + ECS + S3 + a media
pipeline. It honors a stated preference in either direction ("I'm fine with managed
services" vs "everything in our AWS VPC").

---

## Install

> **Prerequisite (all harnesses):** Python 3.11+. Deploying additionally needs the
> [Terraform CLI](https://developer.hashicorp.com/terraform/install) (default backend) or
> the [AWS CLI](https://aws.amazon.com/cli/) (the no-IaC backend).

### Claude Code

Run these two commands in Claude Code:

```
/plugin marketplace add AlexK020908/infra-designer
/plugin install infra-designer@infra-designer-marketplace
```

That's it — `/plan-infra`, `/deploy`, and `/audit` are now available in any repo.

### Codex / Cursor / generic agents

First install the engine as a CLI (gives you an `infra-designer` command on your PATH):

```bash
pipx install infra-designer      # or: pip install infra-designer
```

Then get the agent instructions + components by cloning the repo and pointing your agent
at it:

```bash
git clone https://github.com/AlexK020908/infra-designer.git
```

- **Codex** auto-reads [`infra-plugin/AGENTS.md`](infra-plugin/AGENTS.md) — open the repo (or copy
  `AGENTS.md` into your project) and ask it to design infrastructure.
- **Cursor** — copy [`infra-plugin/adapters/cursor/infra-designer.mdc`](infra-plugin/adapters/cursor/infra-designer.mdc)
  into your workspace's `.cursor/rules/`.
- **Anything with MCP** — register [`infra-plugin/adapters/mcp/server.py`](infra-plugin/adapters/mcp/server.py)
  (see [`adapters/mcp/README.md`](infra-plugin/adapters/mcp/README.md)). This is the universal path.

See [`infra-plugin/adapters/README.md`](infra-plugin/adapters/README.md) for the full
adapter table.

---

## Use it

In Claude Code:

```
/plan-infra a full-stack Next.js app with email login and CRUD, a few hundred users.
            I'm happy to use Vercel + Supabase and don't want to manage servers.
```

It confirms the requirements with you, then writes everything into a per-project folder
**in your current repo**:

```
infra/<project-name>/
  spec.json        # canonical source of truth (hand-off artifact)
  spec.lock.json   # pinned component versions
  diagram.drawio   # AWS-icon diagram (open at app.diagrams.net)
  diagram.mmd      # Mermaid (renders inline in GitHub/IDEs)
```

Then `/deploy` renders the spec to Terraform (or `deploy.sh`) and applies it, and
`/audit` diffs the live infrastructure back against the spec. Each design lives in its
own `infra/<project-name>/` folder, so multiple designs in one repo never overwrite each
other.

On other harnesses, just ask in natural language ("design infra for …", "deploy it",
"audit for drift") — same engine, same files.

## How it works

One canonical `spec.json` is the source of truth; the Terraform, the diagram, and the
audit are all deterministic projections of it. The spec composes **declarative
components** from a registry (`aws.alb`, `aws.ecs.service`, `aws.rds.postgres`,
`web.frontend` (Vercel), `supabase.database`, …), each of which compiles to standard
Terraform. Wiring between components (IAM policies, security-group rules, load-balancer
target groups) is generated from the spec's `edges`.

Full component registry, the wiring model, and the engine CLI are documented in
**[infra-plugin/README.md](infra-plugin/README.md)**.

## Contributing

The main extension point is **authoring new components**. See
[CONTRIBUTING.md](CONTRIBUTING.md) and the component contract in
[infra-plugin/components/CONTRACT.md](infra-plugin/components/CONTRACT.md).

## License

[MIT](LICENSE) © Alex Kang
