Choreo - a graph based diagram design and analysis tool

code-shoily

I’d love to share Choreo — a code-first toolkit designed to help map, visualize, and run metrics on your system architectures.

Choreo embraces the idea of architecture as data. You describe your workflows, pipelines, or data paths declaratively in Elixir, and Choreo builds them up using Yog underneath.

You get both customizable Graphviz DOT layouts, and utilize the built-in architectural validation and analysis.

Supported domains out of the box:

Finite State Machines (Choreo.FSM): Trace state transitions, detect terminal dead-ends, and identify unreachable states.
Workflows (Choreo.Workflow): Map out critical execution paths, identify latency bottlenecks, and verify Saga pattern constraints (e.g. ensuring compensation paths safely reach termination targets).
Data Pipelines (Choreo.Dataflow): Simulate backpressure scenarios, measure stage constraints, and flag unhandled error branches.
Dependency Trees (Choreo.Dependency): Unpack cyclic bottlenecks, clean transitive bloat, and compute Uncle Bob’s structural Instability Metrics.
Threat Models (Choreo.ThreatModel): Run stride evaluations automatically over mapped vectors.

Quick Example:

alias Choreo.FSM

fsm =
  FSM.new()
  |> FSM.add_state(:cart, initial: true)
  |> FSM.add_state(:processing)
  |> FSM.add_state(:completed, final: true)
  |> FSM.add_state(:failed, final: true)
  |> FSM.transition(:cart, :processing, "checkout")
  |> FSM.transition(:processing, :completed, "success")
  |> FSM.transition(:processing, :failed, "error")

# Export stunning diagrams with theming
IO.puts FSM.to_dot(fsm, theme: :dark)

Give the documentation a spin or check the source repo:

https://github.com/code-shoily/choreo

I am actively working with it and bug-fixes will be made, and new features will be added frequently.

9 comments

#library #graphs #diagrams #choreo

3 856 9

2026-09-06 17:17:31 UTC

Most Liked

Show Best Posts
Show All (oldest first)
Show All (newest first)

mudasobwa

Creator of Cure

I checked FSMs and I wonder what does mean plural initial states? It kinda violates everything I know about FInite Automata.

Post #1

code-shoily

I am removing support for NFAs and staying within DFA. My trying to avoid epsilon transitions added more headaches than otherwise.

Thank you again for making me rethink this.

Off-topic but just checked Cure. Wow. I’ll talk more on that channel.

Post #4

code-shoily

I tried out Finitomata yesterday. A brilliant project. I was curious if I could use Choreo + Finitomata somehow. So was playing around a bit and got this Livebook. This should run as-is if you have runbook and helped me appreciate the project more!

Thanks for inspiring this @mudasobwa

Post #6

Last Post!

code-shoily

Added a DSL for easily generating diagrams.

For example the following two snippets are the same:

alias Choreo.Dependency

deps =
  Dependency.new()
  |> Dependency.add_module(:core,       label: "Core Business",  layer: :domain)
  |> Dependency.add_module(:accounts,   label: "Accounts",       layer: :domain)
  |> Dependency.add_module(:orders,     label: "Orders",         layer: :domain)
  |> Dependency.add_module(:auth,       label: "Auth",           layer: :application)
  |> Dependency.add_module(:repo,       label: "Repo",           layer: :infrastructure)
  |> Dependency.add_module(:mailer,     label: "Mailer",         layer: :infrastructure)
  |> Dependency.depends_on(:accounts, :core)
  |> Dependency.depends_on(:orders, :core)
  |> Dependency.depends_on(:orders, :accounts)
  |> Dependency.depends_on(:auth, :accounts)
  |> Dependency.depends_on(:repo, :core)
  |> Dependency.depends_on(:mailer, :orders)

# Analysis
Dependency.Analysis.cyclic_dependencies(deps) # => []
Dependency.Analysis.affected_by(deps, :core)  # all dependents

AND

alias Choreo.Lab.DSL.Dependency, as: DependencyDSL

deps =
  DependencyDSL.dependency do
    cluster "Domain" do
      core = library("Core Business")
      accounts = library("Accounts")
      orders = library("Orders")
    end

    cluster "Application" do
      auth = application("Auth")
    end

    cluster "Infrastructure" do
      repo = package("Repo")
      mailer = package("Mailer")
    end

    accounts ~> core |> depends_on("domain logic")
    orders ~> core |> depends_on("domain logic")
    orders ~> accounts |> calls("account state")
    auth ~> accounts |> calls("identity")
    repo ~> core |> implements("persistence")
    mailer ~> orders |> depends_on("order events")
  end

Polished the example livebook guides, and used more DSL syntax with a cheatsheet of each.

The website is also updated.

Post #9