Examples

These examples show current DiagramPilot Source File patterns for common software architecture diagrams. Use committed examples when you want a richer reference, and use Source Creation templates when you want a small maintained starting point.

Maintained Templates

diagrampilot create docs/architecture.dp.yaml --template architecture
diagrampilot create docs/login-flow.dp.yaml --template flow
diagrampilot create docs/packages.dp.yaml --template package-map
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map

Each command writes a valid *.dp.yaml file, refuses to overwrite an existing file, and prints the next validate and render commands.

Committed Example Sources

Codebase Architecture

Path: examples/codebase-architecture/codebase-architecture.dp.yaml

diagrampilot validate examples/codebase-architecture/codebase-architecture.dp.yaml
diagrampilot render examples/codebase-architecture/codebase-architecture.dp.yaml --out examples/codebase-architecture/codebase-architecture.svg
diagrampilot export examples/codebase-architecture/codebase-architecture.dp.yaml --format mermaid
diagrampilot check examples/codebase-architecture

Use this when a repository needs a compact architecture view with Stable IDs, Groups, local source metadata, and labeled request/write/event edges.

Dependency Map

Path: examples/dependency-map/dependency-map.dp.yaml

diagrampilot validate examples/dependency-map/dependency-map.dp.yaml
diagrampilot render examples/dependency-map/dependency-map.dp.yaml --out examples/dependency-map/dependency-map.svg
diagrampilot export examples/dependency-map/dependency-map.dp.yaml --format mermaid
diagrampilot check examples/dependency-map

Use this for package dependency diagrams such as packages/cli, packages/core, packages/render-svg, packages/export-mermaid, packages/export-d2, packages/export-dot, and packages/icons.

Service Boundary Map

Path: examples/service-boundary-map/service-boundary-map.dp.yaml

diagrampilot validate examples/service-boundary-map/service-boundary-map.dp.yaml
diagrampilot render examples/service-boundary-map/service-boundary-map.dp.yaml --out examples/service-boundary-map/service-boundary-map.svg
diagrampilot export examples/service-boundary-map/service-boundary-map.dp.yaml --format mermaid
diagrampilot check examples/service-boundary-map

Use this to review public, platform, and data boundaries without adding per-object styling fields to DiagramSpec.

Monorepo Overview

Path: examples/monorepo-overview/monorepo-overview.dp.yaml

diagrampilot validate examples/monorepo-overview/monorepo-overview.dp.yaml
diagrampilot render examples/monorepo-overview/monorepo-overview.dp.yaml --out examples/monorepo-overview/monorepo-overview.svg
diagrampilot export examples/monorepo-overview/monorepo-overview.dp.yaml --format mermaid
diagrampilot export examples/monorepo-overview/monorepo-overview.dp.yaml --format d2 --out examples/monorepo-overview/monorepo-overview.d2
diagrampilot export examples/monorepo-overview/monorepo-overview.dp.yaml --format dot --out examples/monorepo-overview/monorepo-overview.dot
diagrampilot check examples/monorepo-overview

This is the medium-complexity example. It demonstrates Stable IDs, Groups, edge labels and edge kinds, local source references, export workflow commands, and SVG Artifact Freshness. Run render --out before check; generated SVG artifacts include deterministic DiagramPilot provenance with source path, source hash, DiagramPilot version, and renderer identity.

Pull Request Architecture Review

Path: examples/pull-request-architecture-review/pull-request-architecture-review.dp.yaml

diagrampilot validate examples/pull-request-architecture-review/pull-request-architecture-review.dp.yaml
diagrampilot render examples/pull-request-architecture-review/pull-request-architecture-review.dp.yaml --out examples/pull-request-architecture-review/pull-request-architecture-review.svg
diagrampilot export examples/pull-request-architecture-review/pull-request-architecture-review.dp.yaml --format mermaid
diagrampilot check examples/pull-request-architecture-review

Use this to show how a pull request can review changed source files, DiagramPilot Source Files, Derived Artifacts, and repo workflow checks together.

System Context Diagram

Path: examples/system-context/system-context.dp.yaml

diagrampilot validate examples/system-context/system-context.dp.yaml
diagrampilot render examples/system-context/system-context.dp.yaml --out examples/system-context/system-context.svg
diagrampilot export examples/system-context/system-context.dp.yaml --format mermaid
diagrampilot check examples/system-context

Use this for a C4-style context view of an AI coding agent, local repository, DiagramPilot CLI, public docs, and pull request review.

Intentionally Broken Repair Example

This broken source is for repair practice. Do not commit it as a passing fixture. Save it temporarily as docs/broken-architecture.dp.yaml, then run:

diagrampilot validate docs/broken-architecture.dp.yaml

version: 1
title: Broken Architecture
nodes:
  - id: web_app
    label: Web App
  - id: api_gateway
    label: API Gateway
edges:
  - id: web_app_to_missing_service
    from: web_app
    to: missing_service
    label: HTTPS

Expected diagnostic shape:

edges[0].to references unknown node "missing_service".
Suggestion: Add a node with id "missing_service" or change edges[0].to to an existing node ID.

Repair by changing edges[0].to from missing_service to api_gateway, then rerun diagrampilot validate docs/broken-architecture.dp.yaml.

Small Inline Style Reference

version: 1
title: Minimal Package Dependency
direction: right
nodes:
  - id: cli
    label: packages/cli
    kind: package
    icon: lucide:terminal
  - id: core
    label: packages/core
    kind: package
    icon: lucide:box
edges:
  - id: cli_to_core
    from: cli
    to: core
    label: validates source
    kind: imports