AnnotatedDiagrams 0.1.22

AnnotatedDiagrams

Core annotations and model library for AnnotatedDiagrams. Define your software architecture using C# attributes and generate diagrams automatically in SVG, Mermaid, PlantUML, and D2 formats.

Installation

dotnet add package AnnotatedDiagrams

Targets netstandard 2.0 — compatible with .NET Framework 4.6.1+, .NET Core, and .NET 5+.

Quick start

1. Declare external nodes and system boundaries (assembly level)

[assembly: DiagramExternalNode("stripe", "Stripe",
    Kind = NodeKind.ExternalSystem, Technology = "REST")]

[assembly: DiagramExternalNode("order-queue", "Order Queue",
    Kind = NodeKind.Queue, Technology = "Azure Service Bus")]

[assembly: DiagramSystemNode("ecommerce", "E-Commerce Platform")]

2. Annotate your classes

[DiagramNode("Order Service",
    Id = "order-svc",
    Kind = NodeKind.Container,
    System = "ecommerce",
    ParentId = "ecommerce",
    Technology = ".NET 9",
    Description = "Handles order processing")]
[DiagramRelation(typeof(PaymentService),
    Kind = RelationKind.Calls, Label = "Charge card")]
[DiagramRelationToExternal("stripe",
    Kind = RelationKind.Calls, Label = "Payment gateway",
    Tags = new[] { "route:POST /charge" })]
[DiagramRelationToExternal("order-queue",
    Kind = RelationKind.Publishes, Label = "Publishes order placed")]
public sealed class OrderService { }

3. Extract and render

var extractor = new ReflectionDiagramExtractor();
var graph = extractor.Extract(new[] { typeof(OrderService).Assembly });

var renderer = new D2Renderer();
var result = renderer.Render(graph, new RenderRequest("Default"));
Console.WriteLine(result.Source); // D2 source

Annotations reference

Assembly-level attributes

Type-level attributes

Direction

Direction.Outbound (default) — this type calls/uses/publishes to the target. Direction.Inbound — this type receives calls from the target (edge is reversed on the graph). Direction.Bidirectional — two-way relationship.

Node kinds

Relation kinds

Uses · Calls · Reads · Writes · DependsOn · Publishes · Subscribes · Emits · Consumes · Hosts · Deploys

Queue visualization

Queue and Topic nodes support two visualization styles, controlled by RenderRequest.QueueVisualization:

Renderers

RenderRequest options

new RenderRequest(
    ViewName: "Default",           // Which view to render
    DropIsolatedNodes: false,      // Remove nodes with no edges
    LeftToRight: true,             // LR layout (false = top-down)
    ShowIcons: true,               // Show node kind icons
    QueueVisualization: QueueVisualization.Annotation)

Graph merging

DiagramGraphMerger.Merge combines graphs from multiple assemblies or services into one:

• Nodes with equal names where at least one is ExternalSystem or a shared-infrastructure kind (Queue, Topic, Database, Cache, FileStore) are merged into a single canonical node.
• Kind priority (highest wins): System > any concrete kind > ExternalSystem.
• Edges are remapped to canonical node IDs; duplicates (same from/to/kind/label) are deduplicated.

var merged = DiagramGraphMerger.Merge(new[] { graphA, graphB });

Related packages

• AnnotatedDiagrams.Runtime — ASP.NET Core middleware that exposes live diagram and traffic-metrics endpoints from a running service.
• AnnotatedDiagrams.Client — MSBuild integration for Blazor WASM projects; generates .graph.json manifests at build time.