Choreo.Lab.DSL.C4 (Choreo v0.12.0)

Copy Markdown View Source

Experimental Livebook-friendly DSL for sketching C4 models.

This Lab DSL compiles to the stable, pipe-first Choreo.C4 builders and returns an ordinary %Choreo.C4{}. It keeps C4 nouns explicit — people, software systems, containers, and components — while relationship verbs make quick architecture sketches read naturally in Livebook.

Examples

iex> import Choreo.Lab.DSL.C4
...> model = c4 do
...>   customer = person("Customer", description: "API consumer")
...>   gateway = system("API Gateway", scope: :in, description: "Routes tenant API traffic")
...>   api = container("Gateway API", parent: gateway, technology: "Phoenix")
...>   db = container("Tenant DB", parent: gateway, technology: "Postgres")
...>
...>   customer ~> api |> uses("Submits API requests", technology: "HTTPS")
...>   api ~> db |> reads("Tenant config", technology: "SQL")
...>   scope gateway
...> end
iex> Choreo.C4.scope(model)
:gateway
iex> model.graph.nodes[:api].parent
:gateway
iex> [{_, _, _, meta} | _] = Choreo.C4.edges_with_meta(model)
iex> meta.label
"Submits API requests"

Relationship edges can use generic labels, typed verbs, or explicit edge:

user ~> system |> uses("Uses")
api ~> db |> reads("Reads tenant config", technology: "SQL")
edge api ~> worker, calls: "Dispatches job"
sends api ~> queue, "Publishes event", technology: "Kafka"

Parent and scope options can use variables bound earlier in the block:

app = system("Application", scope: :in)
api = container("API", parent: app)
auth = component("Auth Controller", parent: api)
scope app

Summary

Types

cluster_decl()
edge_decl()
node_decl()

Functions

actor(arg1 \\ nil, arg2 \\ nil, opts \\ [])
app(arg1 \\ nil, arg2 \\ nil, opts \\ [])
application(arg1 \\ nil, arg2 \\ nil, opts \\ [])
boundary(arg1 \\ nil, arg2 \\ nil, opts \\ [])
c4(list)

Builds a %Choreo.C4{} from a compact Lab DSL block.

c4(opts, list)
calls(arg1 \\ nil, arg2 \\ nil, opts \\ [])
cluster(arg1 \\ nil, arg2 \\ nil, opts \\ [])
component(arg1 \\ nil, arg2 \\ nil, opts \\ [])
consumes(arg1 \\ nil, arg2 \\ nil, opts \\ [])
container(arg1 \\ nil, arg2 \\ nil, opts \\ [])
database(arg1 \\ nil, arg2 \\ nil, opts \\ [])
datastore(arg1 \\ nil, arg2 \\ nil, opts \\ [])
depends(arg1 \\ nil, arg2 \\ nil, opts \\ [])
external_system(arg1 \\ nil, arg2 \\ nil, opts \\ [])
group(arg1 \\ nil, arg2 \\ nil, opts \\ [])
in_scope(arg1 \\ nil, arg2 \\ nil, opts \\ [])
module(arg1 \\ nil, arg2 \\ nil, opts \\ [])
person(arg1 \\ nil, arg2 \\ nil, opts \\ [])
publishes(arg1 \\ nil, arg2 \\ nil, opts \\ [])
reads(arg1 \\ nil, arg2 \\ nil, opts \\ [])
relates(arg1 \\ nil, arg2 \\ nil, opts \\ [])
routes(arg1 \\ nil, arg2 \\ nil, opts \\ [])
scope(arg1 \\ nil, arg2 \\ nil, opts \\ [])
sends(arg1 \\ nil, arg2 \\ nil, opts \\ [])
service(arg1 \\ nil, arg2 \\ nil, opts \\ [])
software_system(arg1 \\ nil, arg2 \\ nil, opts \\ [])
system(arg1 \\ nil, arg2 \\ nil, opts \\ [])
taxonomy()

Returns the vocabulary supported by the C4 DSL.

user(arg1 \\ nil, arg2 \\ nil, opts \\ [])
uses(arg1 \\ nil, arg2 \\ nil, opts \\ [])
verbs()

Compatibility alias for taxonomy/0.

writes(arg1 \\ nil, arg2 \\ nil, opts \\ [])

Types

cluster_decl()

@type cluster_decl() :: %{id: String.t(), opts: keyword()}

edge_decl()

@type edge_decl() :: %{from: Yog.node_id(), to: Yog.node_id(), opts: keyword()}

node_decl()

@type node_decl() :: %{id: Yog.node_id(), builder: atom(), opts: keyword()}

Functions

actor(arg1 \\ nil, arg2 \\ nil, opts \\ [])

app(arg1 \\ nil, arg2 \\ nil, opts \\ [])

application(arg1 \\ nil, arg2 \\ nil, opts \\ [])

boundary(arg1 \\ nil, arg2 \\ nil, opts \\ [])

c4(list)

(macro)

Builds a %Choreo.C4{} from a compact Lab DSL block.

c4(opts, list)

(macro)

calls(arg1 \\ nil, arg2 \\ nil, opts \\ [])

cluster(arg1 \\ nil, arg2 \\ nil, opts \\ [])

component(arg1 \\ nil, arg2 \\ nil, opts \\ [])

consumes(arg1 \\ nil, arg2 \\ nil, opts \\ [])

container(arg1 \\ nil, arg2 \\ nil, opts \\ [])

database(arg1 \\ nil, arg2 \\ nil, opts \\ [])

datastore(arg1 \\ nil, arg2 \\ nil, opts \\ [])

depends(arg1 \\ nil, arg2 \\ nil, opts \\ [])

external_system(arg1 \\ nil, arg2 \\ nil, opts \\ [])

group(arg1 \\ nil, arg2 \\ nil, opts \\ [])

in_scope(arg1 \\ nil, arg2 \\ nil, opts \\ [])

module(arg1 \\ nil, arg2 \\ nil, opts \\ [])

person(arg1 \\ nil, arg2 \\ nil, opts \\ [])

publishes(arg1 \\ nil, arg2 \\ nil, opts \\ [])

reads(arg1 \\ nil, arg2 \\ nil, opts \\ [])

relates(arg1 \\ nil, arg2 \\ nil, opts \\ [])

routes(arg1 \\ nil, arg2 \\ nil, opts \\ [])

scope(arg1 \\ nil, arg2 \\ nil, opts \\ [])

sends(arg1 \\ nil, arg2 \\ nil, opts \\ [])

service(arg1 \\ nil, arg2 \\ nil, opts \\ [])

software_system(arg1 \\ nil, arg2 \\ nil, opts \\ [])

system(arg1 \\ nil, arg2 \\ nil, opts \\ [])

taxonomy()

@spec taxonomy() :: %{
  clusters: [atom()],
  nodes: [atom()],
  edges: [atom()],
  events: [atom()],
  modifiers: [atom()],
  options: [atom()]
}

Returns the vocabulary supported by the C4 DSL.

This is meant as a lightweight Livebook discovery helper when autocomplete is not enough.

iex> taxonomy = Choreo.Lab.DSL.C4.taxonomy()
iex> :person in taxonomy.nodes
true
iex> :container in taxonomy.nodes
true
iex> :uses in taxonomy.edges
true

user(arg1 \\ nil, arg2 \\ nil, opts \\ [])

uses(arg1 \\ nil, arg2 \\ nil, opts \\ [])

verbs()

@spec verbs() :: map()

Compatibility alias for taxonomy/0.

writes(arg1 \\ nil, arg2 \\ nil, opts \\ [])