# @draw-my-architecture/diagram-dsl

> Cloud-aware diagram DSL parser, validator, and normalizer with Azure-first backward compatibility.

Latest version **0.1.4** (published 2026-06-30) · 0 weekly downloads

## Install

```sh
npm install @draw-my-architecture/diagram-dsl
pnpm add @draw-my-architecture/diagram-dsl
yarn add @draw-my-architecture/diagram-dsl
bun add @draw-my-architecture/diagram-dsl
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.4 |
| Published | 2026-06-30 |
| First published | 2026-06-30 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 67.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | petecodes |

## Links

- npm: https://www.npmjs.com/package/@draw-my-architecture/diagram-dsl
- npm.io page: https://npm.io/package/@draw-my-architecture/diagram-dsl

## Recent versions

- 0.1.4 (latest) — 2026-06-30
- 0.1.3 — 2026-06-30
- 0.1.2 — 2026-06-30
- 0.1.0 — 2026-06-30

## README

# @draw-my-architecture/diagram-dsl

Cloud-aware diagram DSL parser, validator, and normalizer with Azure-first backward compatibility.

## DSL syntax reference (line-based markdown DSL)

This DSL is line-based (one declaration per line), markdown-friendly, and comment-tolerant.

- Use `#` or `//` for comments.
- Use `key=value` options.
- Quote values with spaces: `label="My API"`.
- Escape inside quoted values with `\"`, `\\`, `\n`, `\r`, `\t`.

```txt
diagram <id> [label="..."] [provider=<azure|aws|gcp>] [key=value...]
group <id> [label="..."] [parent=<groupId>] [provider=<azure|aws|gcp>] [groupKind=<group|resourceGroup>] [resourceGroup=<groupId|hint>] [style=<hint>] [key=value...]
node <id> <serviceKey> [label="..."] [group=<groupId>] [provider=<azure|aws|gcp>] [shape=<icon|box>] [resourceGroup=<groupId|hint>] [type=<resourceType>] [style=<hint>] [x=<number>] [y=<number>] [key=value...]
edge <sourceNodeId> -> <targetNodeId> [label="..."] [kind=<dependsOn|connectsTo|dataFlow|contains>] [direction=<oneWay|bidirectional>] [terminator=<default|none|back|both>] [route=<auto|manual>] [bends="x,y;x,y"] [protocol=<name>] [port=<value>] [style=<hint>] [key=value...]
note <id> label="..." [attachTo=<nodeOrGroupId>] [x=<number>] [y=<number>] [width=<number>] [height=<number>]
meta <key>=<value>
```

### Required structure

`diagram` is required and only one is allowed:

```txt
diagram main label="My architecture" provider=azure
```

### Declaration details

1. `diagram`: top-level identifier, optional label, optional default provider.
2. `group`: optional containers; supports parent nesting and `groupKind=resourceGroup`.
3. `node`: requires `<id> <serviceKey>`; optional provider/shape/group/resource metadata.
4. `edge`: must use `->`; only node-to-node links are valid.
5. `note`: floating annotation box; `label` is required, `attachTo` draws a dotted amber connector to the target node/group. `x`/`y` override position; `width`/`height` override box size.
6. `meta`: free-form metadata as `meta key=value`.

### Validation semantics

- Providers: `azure | aws | gcp`
- Node shape: `icon | box`
- Group kind: `group | resourceGroup`
- Edge direction: `oneWay | bidirectional`
- Edge terminator: `default | none | back | both` (controls arrowhead rendering)
- Edge route mode: `auto | manual`
- Edge bend points:
  - Use `bends="x,y;x,y"` (semicolon-separated coordinate pairs).
  - Coordinates must be finite numbers in range `-100000..100000`.
  - `bends` are only valid for manual routing (`route=manual`; implied when omitted).
- Edge kind: any string parses; recommended kinds are `dependsOn`, `connectsTo`, `dataFlow`, `contains`
- Node coordinates:
  - If one of `x`/`y` is present, both must be present.
  - Must be finite numbers in range `-100000..100000`.
- Note annotations:
  - `label` is required.
  - `attachTo` must reference an existing node or group id.
  - `id` must be unique and not conflict with any node or group id.
  - `x`/`y`, if provided, must both be present and be finite numbers.
  - `width`/`height`, if provided, must be positive numbers.

### Defaults (normalization)

- Diagram provider defaults to `azure`.
- Node shape defaults to `icon`.
- Group kind defaults to `group`.
- Edge kind defaults to `connectsTo`.
- Edge direction defaults to `oneWay`.
- Edge terminator defaults to `default` (forward arrow at target).

## Example (mixed cloud + resource groups + note)

```txt
diagram checkout label="Checkout Platform" provider=azure
group rg-app groupKind=resourceGroup label="App Resource Group"
group apps label="Applications" parent=rg-app
node api appService label="Checkout API" group=apps provider=azure shape=icon resourceGroup=rg-app type=sites x=220 y=120
node ordersDb sqlDatabase label="Orders DB" group=apps provider=azure shape=icon resourceGroup=rg-app
node cdn cloudFront label="Edge CDN" provider=aws shape=icon
edge cdn -> api label="HTTPS" kind=dataFlow direction=oneWay protocol=https port=443
edge api -> ordersDb label="reads/writes" kind=dataFlow
note n1 label="Primary data store\ncopied nightly" attachTo=ordersDb
meta environment=prod
```

## API

```ts
import {
  applyNodeLayout,
  compileAzureDsl,
  normalizeAzureDsl,
  parseAzureDsl,
  serializeAzureDsl,
  validateAzureDsl
} from '@draw-my-architecture/diagram-dsl';

const ast = parseAzureDsl(source);
const validation = validateAzureDsl(ast);
const model = validation.isValid ? normalizeAzureDsl(ast) : undefined;
const updated = model ? applyNodeLayout(model, { api: { x: 320, y: 180 } }) : undefined;
const persistedDsl = updated ? serializeAzureDsl(updated) : source;
```

`normalizeAzureDsl` emits node fields needed for future icon resolution:

- `model.provider` (resolved diagram provider, defaults to `azure`)
- `node.provider` and `node.cloud.provider` (`azure|aws|gcp`)
- `node.shape` and `node.designer.shapeVariant` (`icon/providerIcon` vs `box/standardBox`)
- `group.kind` and `group.designer.isResourceGroup`
- `edge.direction` plus `edge.metadata.routeMode` / `edge.metadata.bendPoints`
- `edge.metadata.protocol` / `edge.metadata.port`
- `node.azure.serviceKey`
- `node.azure.resourceType` (optional)
- `node.azure.iconKey` (preserves legacy Azure format)
- `node.layout` (`{ x, y }`, optional)

Backward compatibility notes:

- Existing DSL without `provider`, `shape`, `groupKind`, `resourceGroup`, `direction`, `protocol`, or `port` still parses/normalizes.
- Omitted provider defaults to `azure`.
- Serializer keeps legacy Azure output compact (no forced `provider=azure`).

Node layout coordinates are still optional. Add both `x=<number>` and `y=<number>` to persist placement:

```txt
node api appService x=220 y=120
```

---
_Source: https://npm.io/package/@draw-my-architecture/diagram-dsl · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._