# `Choreo.Infrastructure`
[🔗](https://github.com/code-shoily/choreo/blob/v0.14.1/lib/choreo/infrastructure.ex#L1)

Cloud network and infrastructure topology preset built on top of Choreo's rendering primitives.

`Choreo.Infrastructure` is a **domain-specific vocabulary layer** that adds cloud-network
concepts — VPCs, subnets, compute, load balancers, managed databases, storage — on top of
the same graph, cluster, and rendering stack used by `Choreo`. It is *not* a parallel
implementation: it shares `Choreo.Theme` and the internal rendering helpers behind the `Yog`
rendering pipeline directly.

The key additions over plain `Choreo` are:

  * **Typed cluster boundaries** — `:vpc`, `:subnet_public`, `:subnet_private` carry security
    semantics (e.g. databases should not be in public subnets) that generic clusters do not.
  * **`Choreo.Infrastructure.Analysis`** — structural audit rules that inspect topology against
    those security semantics (direct internet-to-private-subnet links, misplaced databases, etc.).
  * **Network vocabulary** — `add_vpc/3`, `add_compute/3`, `add_managed_db/3` etc. as
    intent-revealing builders instead of the generic `add_cluster/3` / `add_service/3`.

Node colors and shapes are resolved through `Choreo.Theme` (`:internet`, `:compute`, and
`:managed_db` are first-class theme types), so the full theme system — including `:dark`,
`:warm`, `:forest`, `:ocean` — applies to infrastructure diagrams without any extra
configuration.

## Element types

  * `:internet` — public gateway or client zone
  * `:load_balancer` — traffic proxy (e.g. ALB, ingress)
  * `:compute` — application runner (EC2, ECS task, Kubernetes pod)
  * `:managed_db` — stateful database (RDS, Aurora)
  * `:storage` — blob/file storage (S3, EFS)

## Network boundaries (Clusters)

  * `:vpc` — Virtual Private Cloud container
  * `:subnet_public` — Public subnet zone (internet-facing)
  * `:subnet_private` — Private subnet zone (isolated)

## Quick Start

    infra =
      Choreo.Infrastructure.new()
      |> Choreo.Infrastructure.add_internet(:gateway, label: "Internet Gateway")
      |> Choreo.Infrastructure.add_vpc("vpc_main", label: "Production VPC")
      |> Choreo.Infrastructure.add_subnet_public("subnet_dmz", label: "Public Subnet", parent: "vpc_main")
      |> Choreo.Infrastructure.add_subnet_private("subnet_app", label: "Private Subnet", parent: "vpc_main")
      |> Choreo.Infrastructure.add_load_balancer(:alb, label: "ALB", cluster: "subnet_dmz")
      |> Choreo.Infrastructure.add_compute(:api, label: "API Service", cluster: "subnet_app")
      |> Choreo.Infrastructure.add_managed_db(:db, label: "Postgres RDS", cluster: "subnet_app")
      |> Choreo.Infrastructure.connect(:gateway, :alb)
      |> Choreo.Infrastructure.connect(:alb, :api)
      |> Choreo.Infrastructure.connect(:api, :db)

    # Check for architecture warning violations
    warnings = Choreo.Infrastructure.Analysis.validate(infra)

    dot = Choreo.Infrastructure.to_dot(infra)
    mermaid = Choreo.Infrastructure.to_mermaid(infra)

# `t`

```elixir
@type t() :: %Choreo.Infrastructure{
  clusters: %{required(String.t()) => map()},
  edge_meta: %{optional(Yog.Multi.Graph.edge_id()) => map()},
  graph: Yog.Multi.Graph.t()
}
```

# `add_cluster`

```elixir
@spec add_cluster(t(), String.t(), keyword()) :: t()
```

Adds a generic cluster boundary to the infrastructure diagram.

# `add_compute`

```elixir
@spec add_compute(t(), Yog.node_id(), keyword()) :: t()
```

Adds a compute workload runner node (EC2, ECS task, Kubernetes pod).

# `add_internet`

```elixir
@spec add_internet(t(), Yog.node_id(), keyword()) :: t()
```

Adds an internet gateway or public internet entrypoint node.

# `add_load_balancer`

```elixir
@spec add_load_balancer(t(), Yog.node_id(), keyword()) :: t()
```

Adds a load balancer proxy node (ALB, Ingress Controller).

# `add_managed_db`

```elixir
@spec add_managed_db(t(), Yog.node_id(), keyword()) :: t()
```

Adds a managed database node (RDS, Aurora, DynamoDB).

# `add_storage`

```elixir
@spec add_storage(t(), Yog.node_id(), keyword()) :: t()
```

Adds a storage bucket or block storage node (S3, EFS).

# `add_subnet_private`

```elixir
@spec add_subnet_private(t(), String.t(), keyword()) :: t()
```

Adds a private subnet cluster boundary.

# `add_subnet_public`

```elixir
@spec add_subnet_public(t(), String.t(), keyword()) :: t()
```

Adds a public subnet cluster boundary.

# `add_vpc`

```elixir
@spec add_vpc(t(), String.t(), keyword()) :: t()
```

Adds a VPC cluster network boundary.

# `clusters`

```elixir
@spec clusters(t() | Choreo.t()) :: %{required(String.t()) => map()}
```

Returns all cluster definitions in the infrastructure diagram.

# `connect`

```elixir
@spec connect(t(), Yog.node_id(), Yog.node_id(), keyword()) :: t()
```

Connects two infrastructure nodes together.

# `edges`

```elixir
@spec edges(t() | Choreo.t()) :: [{Yog.node_id(), Yog.node_id(), any()}]
```

Returns all edges.

# `edges_with_meta`

```elixir
@spec edges_with_meta(t() | Choreo.t()) :: [
  {Yog.node_id(), Yog.node_id(), number(), map()}
]
```

Returns all edges with their metadata as `{from, to, cost, meta}` tuples.

# `from_choreo`

```elixir
@spec from_choreo(Choreo.t()) :: t()
```

Converts a generic `%Choreo{}` diagram into a `%Choreo.Infrastructure{}` diagram.

# `new`

```elixir
@spec new(keyword()) :: t()
```

Creates a new empty cloud infrastructure diagram.

# `nodes`

```elixir
@spec nodes(t() | Choreo.t()) :: [Yog.node_id()]
```

Returns all node IDs.

# `theme`

```elixir
@spec theme(atom(), keyword()) :: Choreo.Theme.t()
```

Returns a theme for `Choreo.Infrastructure`.

## Examples

    iex> theme = Choreo.Infrastructure.theme(:default, graph_rankdir: :lr)
    iex> theme.graph_rankdir
    :lr

# `to_choreo`

# `to_dot`

# `to_dot`

```elixir
@spec to_dot(t() | Choreo.t(), keyword()) :: String.t()
```

Renders the infrastructure topology to DOT format.

## Options

  * `:theme` — `:default`, `:dark`, `:minimal`, `:warm`, `:forest`, `:ocean`, or a `Choreo.Theme` struct
  * `:highlighted_nodes` — list of node IDs to highlight
  * `:highlighted_edges` — list of edge IDs or `{from, to}` tuples to highlight

# `to_graph`

```elixir
@spec to_graph(t() | Choreo.t()) :: Yog.Multi.Graph.t()
```

Returns the raw `Yog.Multi.Graph` struct underpinning the infrastructure diagram.

# `to_mermaid`

# `to_mermaid`

```elixir
@spec to_mermaid(t() | Choreo.t(), keyword()) :: String.t()
```

Renders the infrastructure topology to Mermaid.js syntax.

## Options

  * `:syntax` — `:flowchart` (default) or `:architecture` (native
    `architecture-beta` diagram type)
  * `:theme` — `:default`, `:dark`, `:minimal`, `:warm`, `:forest`, `:ocean`, or a `Choreo.Theme` struct
  * `:direction` — `:td` (default), `:lr`, `:rl`, `:bt`
  * `:highlighted_nodes` — list of node IDs to highlight
  * `:highlighted_edges` — list of edge IDs or `{from, to}` tuples to highlight

# `to_simple_graph`

```elixir
@spec to_simple_graph(t() | Choreo.t(), keyword()) :: Yog.Graph.t()
```

Collapses parallel edges into a simple `Yog.Graph` for algorithm analysis.

---

*Consult [api-reference.md](api-reference.md) for complete listing*