AshDiagram.Data.Architecture (AshDiagram v0.2.1)

View Source

Provides functions to create Architecture Diagrams for Ash applications.

This module generates C4 context diagrams that visualize Ash application architecture with nested boundaries organized by OTP applications:

  • BEAM VM: Root boundary containing all OTP applications
  • OTP Applications: Individual applications (like :ash, :my_app)
  • Domains: Ash domains within user applications
  • Resources: Individual Ash resources within domains
  • Data Layers: Data storage systems organized by their OTP application

Architecture Hierarchy

BEAM
├── ash (OTP Application)
│   └── Mnesia (Data Layer)
├── my_app (OTP Application)
│   └── Blog (Domain)
│       ├── User (Resource)
│       └── Post (Resource)
└── External Systems
    └── PostgreSQL (External Data Layer)

Data Layer Organization

Data layers are automatically placed in the correct OTP application boundary using Application.get_application/1. For example:

Summary

Types

option()

Configuration option for architecture diagram generation.

options()

List of configuration options for architecture diagram generation.

Functions

for_applications(applications, options \\ [])

Generates an architecture diagram for the given OTP applications.

for_domains(domains, options \\ [])

Generates an architecture diagram for the given Ash domains.

for_resources(resources, options \\ [])

Generates an architecture diagram for the given Ash resources.

Types

option()

@type option() ::
  {:name, :full | :short} | {:show_private?, boolean()} | {:title, String.t()}

Configuration option for architecture diagram generation.

Available options:

  • {:name, :full | :short} - How to display resource names. :full shows complete module names, :short shows shortened names with common prefixes removed

  • {:show_private?, boolean()} - Whether to include private relationships in the diagram
  • {:title, String.t()} - Custom title for the diagram

options()

@type options() :: [option()]

List of configuration options for architecture diagram generation.

Functions

for_applications(applications, options \\ [])

@spec for_applications(applications :: [Application.app()], options :: options()) ::
  AshDiagram.t()

Generates an architecture diagram for the given OTP applications.

Creates a C4 context diagram showing the architecture hierarchy of Ash applications within the specified OTP applications. All domains from the applications are included.

Parameters

  • applications - List of OTP application names (e.g., [:my_app, :other_app])
  • options - Keyword list of options, see option/0 for available options

Examples

# Generate diagram for a single application
AshDiagram.Data.Architecture.for_applications([:my_app])

# Generate diagram with full module names
AshDiagram.Data.Architecture.for_applications([:my_app], name: :full)

# Include private resources and relationships
AshDiagram.Data.Architecture.for_applications([:my_app], show_private?: true)

for_domains(domains, options \\ [])

@spec for_domains(domains :: [Ash.Domain.t()], options :: options()) :: AshDiagram.t()

Generates an architecture diagram for the given Ash domains.

Creates a C4 context diagram showing the architecture hierarchy for all resources within the specified domains.

Parameters

  • domains - List of Ash domain modules (e.g., [MyApp.Blog, MyApp.Accounts])
  • options - Keyword list of options, see option/0 for available options

Examples

# Generate diagram for specific domains
AshDiagram.Data.Architecture.for_domains([MyApp.Blog, MyApp.Accounts])

# Generate diagram with a custom title
AshDiagram.Data.Architecture.for_domains([MyApp.Blog], title: "Blog Domain Architecture")

for_resources(resources, options \\ [])

@spec for_resources(resources :: [Ash.Resource.t()], options :: options()) ::
  AshDiagram.t()

Generates an architecture diagram for the given Ash resources.

Creates a C4 context diagram showing the complete architecture hierarchy including:

  • BEAM VM as the root boundary
  • OTP applications containing the resources and their data layers
  • Domain boundaries within applications
  • Resources within domains
  • Data layer connections
  • Resource relationships

Parameters

  • resources - List of Ash resource modules (e.g., [MyApp.User, MyApp.Post])
  • options - Keyword list of options, see option/0 for available options

Examples

# Generate diagram for specific resources
AshDiagram.Data.Architecture.for_resources([MyApp.User, MyApp.Post])

# Use full module names and show private relationships
AshDiagram.Data.Architecture.for_resources(
  [MyApp.User, MyApp.Post],
  name: :full,
  show_private?: true
)

# Add a custom title
AshDiagram.Data.Architecture.for_resources(
  [MyApp.User, MyApp.Post],
  title: "User Management Architecture"
)