Choreo.Infrastructure (Choreo v0.14.0)

Copy Markdown View Source

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)

Summary

Types

t()

Functions

add_cluster(infra, name, opts \\ [])

Adds a generic cluster boundary to the infrastructure diagram.

add_compute(infra, id, opts \\ [])

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

add_internet(infra, id, opts \\ [])

Adds an internet gateway or public internet entrypoint node.

add_load_balancer(infra, id, opts \\ [])

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

add_managed_db(infra, id, opts \\ [])

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

add_storage(infra, id, opts \\ [])

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

add_subnet_private(infra, name, opts \\ [])

Adds a private subnet cluster boundary.

add_subnet_public(infra, name, opts \\ [])

Adds a public subnet cluster boundary.

add_vpc(infra, name, opts \\ [])

Adds a VPC cluster network boundary.

clusters(arg1)

Returns all cluster definitions in the infrastructure diagram.

connect(infra, from, to, opts \\ [])

Connects two infrastructure nodes together.

edges(arg1)

Returns all edges.

edges_with_meta(system)

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

from_choreo(system)

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

new(opts \\ [])

Creates a new empty cloud infrastructure diagram.

nodes(arg1)

Returns all node IDs.

theme(name \\ :default, overrides \\ [])

Returns a theme for Choreo.Infrastructure.

to_choreo(infra)
to_dot(infra_or_system)
to_dot(infra, opts)

Renders the infrastructure topology to DOT format.

to_graph(arg1)

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

to_mermaid(infra_or_system)
to_mermaid(infra, opts)

Renders the infrastructure topology to Mermaid.js syntax.

to_simple_graph(infra_or_system, opts \\ [])

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

Types

t()

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

Functions

add_cluster(infra, name, opts \\ [])

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

Adds a generic cluster boundary to the infrastructure diagram.

add_compute(infra, id, opts \\ [])

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

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

add_internet(infra, id, opts \\ [])

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

Adds an internet gateway or public internet entrypoint node.

add_load_balancer(infra, id, opts \\ [])

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

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

add_managed_db(infra, id, opts \\ [])

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

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

add_storage(infra, id, opts \\ [])

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

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

add_subnet_private(infra, name, opts \\ [])

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

Adds a private subnet cluster boundary.

add_subnet_public(infra, name, opts \\ [])

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

Adds a public subnet cluster boundary.

add_vpc(infra, name, opts \\ [])

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

Adds a VPC cluster network boundary.

clusters(arg1)

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

Returns all cluster definitions in the infrastructure diagram.

connect(infra, from, to, opts \\ [])

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

Connects two infrastructure nodes together.

edges(arg1)

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

Returns all edges.

edges_with_meta(system)

@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(system)

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

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

new(opts \\ [])

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

Creates a new empty cloud infrastructure diagram.

nodes(arg1)

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

Returns all node IDs.

theme(name \\ :default, overrides \\ [])

@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(infra)

to_dot(infra_or_system)

to_dot(infra, opts)

@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(arg1)

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

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

to_mermaid(infra_or_system)

to_mermaid(infra, opts)

@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(infra_or_system, opts \\ [])

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

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