AWS SAM Graph Generator

Generate a Mermaid flowchart from an AWS SAM (or plain CloudFormation) template, so you can see what a stack actually does without re-reading the whole YAML file.

It reads the Resources section, figures out what triggers what (API Gateway routes, S3/SNS/SQS/DynamoDB/Kinesis event sources, EventBridge schedules) and what each Lambda function reads/writes (via Environment variables and SAM policy templates like DynamoDBCrudPolicy), and renders it as a flowchart.

Usage

# format
npx sam-graph <sam-template.yml>

# example
npx sam-graph template.yml

# or if want to write to a file
npx sam-graph template.yml -o template.mermaid

This prints a ```mermaid fenced block to stdout — paste it straight into a GitHub README, a Notion page, or the Mermaid Live Editor.

# Write straight into a docs file (fenced automatically because of the .md extension)
npx sam-graph template.yaml -o ARCHITECTURE.md

# Write raw Mermaid syntax (no fence) to a .mmd file, e.g. for mermaid-cli
npx sam-graph template.yaml --raw -o diagram.mmd

# Left-to-right instead of the default top-down layout
npx sam-graph template.yaml -d LR

Usage:
  sam-graph <template.yaml> [options]

Options:
  -o, --output <file>     Write to a file instead of stdout.
                           .mmd/.mermaid extension writes raw Mermaid syntax;
                           any other extension (e.g. .md) wraps it in a
                           ```mermaid fenced code block.
  -d, --direction <dir>   Flowchart direction: TD, LR, RL, BT (default: TD).
  --raw                   Print raw Mermaid syntax to stdout (no code fence).
  -h, --help              Show help.
  -v, --version           Show the installed version.

What it draws

• Nodes: every resource in Resources, shaped/iconed by type (λ Lambda, 🌐 API Gateway, 🗄️ DynamoDB/RDS, 🪣 S3, 📢 SNS, 📥 SQS, ⏰ schedules/rules, 🔀 Step Functions, ...). Unrecognized types still get a plain node so nothing is silently dropped.
• Solid edges: explicit triggers — taken from each function's Events block (API routes with method + path, S3/SNS/SQS/DynamoDB Stream/Kinesis event sources, and Schedule/EventBridgeRule events, which get their own synthetic node per event since they aren't separate resources), and from a standalone AWS::Events::Rule's own EventPattern/Targets (a synthetic node summarizes what the rule listens for, and each target it invokes — e.g. an AWS::Events::ApiDestination — gets its own outgoing edge).
• Dashed "uses" edges: inferred from Ref / Fn::GetAtt / Fn::Sub references inside any resource's Properties (env vars, SAM policy templates like DynamoDBCrudPolicy/SNSPublishMessagePolicy, destination configs, ApiDestination connections, CloudWatch Alarm dimensions, ...) that aren't already covered by an explicit trigger edge. Labeled with the target's CloudFormation type (e.g. AWS::SQS::Queue) so it's clear what kind of service is being reached, not just its logical ID. Lambda layers are always excluded from this pass; IAM roles are only excluded when referenced by a Function (its own execution role is boilerplate every function has) — an IAM role referenced by anything else, like the role an EventBridge Rule target assumes to invoke an API destination, is shown.
• API Gateway/HTTP API events without an explicit RestApiId/ApiId are drawn against a shared "implicit" API node (ServerlessRestApi / ServerlessHttpApi), matching what SAM auto-creates for you.

Both short-form YAML tags (!Ref, !GetAtt, !Sub, ...) and long-form (Fn::Ref, {"Fn::GetAtt": [...]}) are supported — the parser normalizes short-form tags before graph-building, so both templates produce the same diagram.

Try it on the example templates

node bin/sam-graph.js examples/order-service.yaml
node bin/sam-graph.js examples/event-bridge.yml

Local development

npm install
npm test

Limitations

This is a static analysis, not a simulation — it won't resolve values that depend on Fn::If/conditions, nested stacks, or CDK-synthesized templates with generated logical IDs. Deeply parameterized Fn::Sub strings only resolve ${LogicalId} / ${LogicalId.Attribute} tokens; arbitrary string concatenation is not evaluated.

License

MIT