Choreo.UML (Choreo v0.9.0)

UML Class and Struct Diagram builder on top of Yog.

Choreo.UML models software component architectures — classes, structs, behaviors, protocols, and interfaces — with fields and functions, and standard structural UML relationships.

Node types

:class / :struct / :behavior / :protocol / :interface

Relationship types

:inherits — solid line with hollow arrowhead (--|>) representing inheritance or behavior adoption.
:realizes — dashed line with hollow arrowhead (..|>) representing protocol implementation.
:associates — solid line with solid arrowhead (-->) representing composition or nesting.
:depends — dashed line with open arrowhead (..>) representing invocation or dependency.

Quick Start

uml =
  Choreo.UML.new()
  |> Choreo.UML.add_class(:user,
    type: :struct,
    fields: [%{name: :id, type: :integer}],
    functions: [%{name: "authenticate", arity: 1}]
  )
  |> Choreo.UML.add_class(:auth_provider,
    type: :behavior,
    functions: [%{name: "verify", arity: 1}]
  )
  |> Choreo.UML.add_relationship(:user, :auth_provider, type: :realizes, label: "implements")

dot = Choreo.UML.to_dot(uml)
mermaid = Choreo.UML.to_mermaid(uml)

Diagram

digraph G { graph [rankdir=TB, bgcolor="#ffffff", splines=spline, nodesep=1.2, ranksep=1.2]; node [shape=plain, style=filled, fillcolor="transparent", fontname="Helvetica", fontsize=11, fontcolor="#1e293b"]; edge [color="#475569", style=solid, fontname="Helvetica", fontsize=9, penwidth=1.0]; user [label=<

«struct»
user

+ id : integer

+ authenticate(1)

>]; auth_provider [label=<

«behavior»
auth_provider

+ verify(1)

>]; user -> auth_provider [penwidth="1.0", color="#475569", arrowhead="empty", style="dashed", fontsize="9", fontname="Helvetica", label="implements"]; }

Summary

Types

class_id()

t()

Functions

add_class(uml, id, opts \\ [])

Adds a class, struct, behavior, or protocol to the diagram.

add_relationship(uml, from, to, opts \\ [])

Adds a structural relationship between two classes/components.

new(opts \\ [])

Initializes a new, empty UML diagram.

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

Returns a theme for the UML diagram.

to_dot(uml, opts \\ [])

Renders the UML diagram to Graphviz DOT syntax.

to_mermaid(uml, opts \\ [])

Renders the UML diagram to Mermaid.js syntax.

Types

class_id()

@type class_id() :: Yog.node_id()

t()

@type t() :: %Choreo.UML{
  edge_meta: %{optional(Yog.Multi.Graph.edge_id()) => map()},
  graph: Yog.Multi.Graph.t(),
  strict: boolean(),
  strict_contract_validation: boolean()
}

Functions

add_class(uml, id, opts \\ [])

@spec add_class(t(), class_id(), keyword()) :: t()

Adds a class, struct, behavior, or protocol to the diagram.

Options

:label (String.t/0) - Visual label for the class (defaults to ID string).
:type - The UML class type: :class, :struct, :behavior, :protocol, or :interface. The default value is :class.
:fields (term/0) - List of fields/attributes. The default value is [].
:functions (term/0) - List of functions/operations. The default value is [].

Examples

iex> uml = Choreo.UML.new()
...> |> Choreo.UML.add_class(:user, type: :struct, fields: [%{name: :id, type: :integer}])
iex> %Choreo.UML{} = uml
iex> Map.has_key?(uml.graph.nodes, :user)
true

add_relationship(uml, from, to, opts \\ [])

@spec add_relationship(t(), class_id(), class_id(), keyword()) :: t()

Adds a structural relationship between two classes/components.

Options

:type - Required. The connection relationship type.
:label (String.t/0) - Optional label/text on the relationship line.

Examples

iex> uml = Choreo.UML.new()
...> |> Choreo.UML.add_class(:user)
...> |> Choreo.UML.add_class(:profile)
...> |> Choreo.UML.add_relationship(:user, :profile, type: :associates, label: "has_one")
iex> %Choreo.UML{} = uml
iex> map_size(uml.graph.edges)
1

new(opts \\ [])

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

Initializes a new, empty UML diagram.

Options

:strict_contract_validation - if true, validates that any class implementing a behavior/protocol/interface implements all its required functions (default: false).
:strict - if true, add_relationship/4 raises when an endpoint does not already exist (default: false).

Examples

iex> uml = Choreo.UML.new()
iex> %Choreo.UML{} = uml
iex> uml.strict_contract_validation
false

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

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

Returns a theme for the UML diagram.

Examples

iex> theme = Choreo.UML.theme(:dark)
iex> theme.graph_bgcolor
"#0f172a"

to_dot(uml, opts \\ [])

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

Renders the UML diagram to Graphviz DOT syntax.

Examples

iex> uml = Choreo.UML.new() |> Choreo.UML.add_class(:user)
iex> dot = Choreo.UML.to_dot(uml)
iex> dot =~ "digraph"
true

to_mermaid(uml, opts \\ [])

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

Renders the UML diagram to Mermaid.js syntax.

Examples

iex> uml = Choreo.UML.new() |> Choreo.UML.add_class(:user)
iex> Choreo.UML.to_mermaid(uml, syntax: :flowchart) =~ "graph"
true
iex> Choreo.UML.to_mermaid(uml, syntax: :class_diagram) =~ "classDiagram"
true