StackMap is a CLI-first infrastructure visualization tool designed to automatically generate interactive architecture diagrams from infrastructure code and live AWS environments. It scans Terraform states, CloudFormation templates, SAM inputs, and live AWS accounts to produce evidence-based, editable architecture maps with inferred relationships, smart groupings, cost forecasting, drift detection, and live operational context.
Key Features:
Automatically generates architecture diagrams from real infrastructure
Live AWS scanning with relationship inference for API Gateway, Lambda, ECS, DynamoDB, S3, and other services
Interactive visualization with zooming, panning, search, filtering, and component views
Smart groupings for large graphs and layered architecture organization
Editable maps to refine incomplete inferences or add custom elements
Drift detection between Infrastructure as Code (IaC) and live AWS states
Audience & Benefit:
Ideal for platform engineers, DevOps teams, cloud architects, and infrastructure teams seeking faster, more accurate architecture visibility. StackMap reduces manual diagram updates by generating diagrams directly from infrastructure, enabling better decision-making with evidence-based insights.
Installable via winget as a professional tool for automated infrastructure visualization workflows.
README
StackMap
Architecture diagrams that generate themselves from your infrastructure code and live AWS accounts.
StackMap is a CLI-first infrastructure visualization and architecture inference tool. It scans real infrastructure inputs, live AWS accounts, and repository sources, then produces interactive architecture maps with inferred relationships, smart grouping, Step Functions workflow views, cost forecasting, drift detection, live logs, billing-aware usage imports, and editable presentation workflows.
Instead of keeping diagrams up to date by hand, you point StackMap at what actually exists, inspect the evidence behind the generated graph, refine anything inference cannot know, and share the result as JSON, HTML, or the local interactive viewer.
What StackMap Does
StackMap turns infrastructure into:
interactive architecture diagrams
grouped system/component views for larger graphs
evidence-rich inferred service relationships
Step Functions workflow inspection from ASL definitions
editable architecture maps when inference is incomplete
diffable snapshots of infrastructure over time
live AWS operational context when explicitly enabled or clicked on demand
exportable HTML and JSON outputs
It is designed for platform engineers, DevOps teams, cloud architects, and anyone who needs fast, trustworthy architecture visibility from real infrastructure.
Core Capabilities
Infrastructure scanning and parsing
StackMap can work with:
Terraform state
CloudFormation templates / JSON
AWS SAM-style inputs
repository-wide infrastructure discovery
live AWS account scans
multi-account AWS scans
Interactive architecture UI
The StackMap web UI supports:
zooming and panning
search
category and relationship filtering
component landing views for large graphs
smart grouping overlays for large AWS graphs
smart component landing pages with grouping confidence, parent-scope filters, and an unlinked-resource bucket
Step Functions state-machine inspection from Terraform, CloudFormation/SAM, and live AWS scans
edge confidence and evidence inspection for inferred live AWS relationships
low-confidence edge filtering
dependency tracing from the detail panel
findings and suspicious-pattern surfacing
forecasted cost overlays with per-resource usage inputs
optional AWS billing and CloudWatch usage import for current-vs-forecast cost comparisons
optional CloudWatch log viewer for selected resources or all visible resources
drift badges and summary bars when comparing IaC vs live state
minimap navigation
diff and timeline-oriented views
presentation mode
Edit and correction mode
StackMap is not only a viewer. It also supports correcting the generated architecture when inference is incomplete.
Current editor features include:
hide noisy resources
restore hidden resources
add custom nodes
add custom links
recolor custom links
move nodes between layers
reorder nodes within the same layer
create custom layers
reorder layers
delete empty custom layers
undo / redo
import / export local edit overlays
Layered architecture model
StackMap organizes infrastructure into architecture lanes such as:
frontend
api
serverless
compute
security/auth
data
Users can also create custom layers for diagrams that need more structure than the default model.
Multi-account AWS visibility
StackMap can scan across multiple AWS accounts and merge them into one graph. This is useful when systems are split across development, sandbox, shared services, and production accounts.
Supported multi-account patterns include:
explicit account / role assumption input
AWS named profile-based scanning
cross-account edge visualization when relevant
Live AWS relationship inference
Live AWS scans now run a post-scan inference pass after resources are collected. The goal is to turn a raw inventory into a useful architecture graph.
The inference engine can resolve relationships such as:
API Gateway REST/v2 routes invoking Lambda functions from integration URIs
API Gateway invoking Lambda functions from Lambda resource policies and execute-api SourceArn
Lambda and ECS workloads accessing DynamoDB, S3, SQS, SNS, Secrets Manager, Step Functions, and related services from IAM role policies
Lambda event source mappings from DynamoDB Streams, SQS, and Kinesis
CloudFront origins pointing at S3, ALB, API Gateway, or custom origins when resolvable
Route53 aliases and records pointing at CloudFront, ALB, API Gateway, and S3 endpoints when resolvable
ALB/NLB listener and target group paths into ECS services, EC2 instances, IP targets, or Lambda targets where AWS exposes that data
ECS services connected to task definitions, task roles, target groups, security groups, subnets, and downstream resources inferred from task role permissions
Each inferred edge can include metadata such as rule name, confidence, human-readable evidence, and the AWS API calls that supplied the evidence. High confidence means direct AWS configuration points to the target, medium confidence usually means IAM policy or SourceArn evidence implies the relationship, and low confidence is reserved for heuristics or network reachability context.
StackMap intentionally does not treat shared VPCs or shared security groups as application data flow by default. Network relationships are useful topology context, but functional data-flow edges require stronger evidence.
Diff / timeline support
StackMap can compare infrastructure snapshots and visualize:
added resources
removed resources
modified resources
changed-only views
AWS-aware visuals
The UI supports AWS-specific visual identity with official AWS icon assets where mapped, plus fallbacks for unmapped resource types.
Installation
Recommended: Homebrew on macOS
Stable install:
brew tap ziadelraggal/homebrew-stackmap
brew install ziadelraggal/homebrew-stackmap/stackmap
Verify install:
stackmap version
stackmap --help
Update:
brew upgrade stackmap
Uninstall:
brew uninstall stackmap
Bleeding-edge Homebrew install from source
If you want the latest unreleased changes:
brew tap ziadelraggal/homebrew-stackmap
brew install --HEAD ziadelraggal/homebrew-stackmap/stackmap
Install from source
Requirements:
Python 3.10+
Node.js and npm for frontend asset generation when packaging locally
stackmap scan-aws --profile dev --output aws-output.json --serve
Enable live CloudWatch logs in the viewer for that profile:
stackmap scan-aws --profile dev --output aws-output.json --serve --live-logs
Enable AWS billing and usage metric imports in the viewer:
stackmap scan-aws --profile dev --output aws-output.json --serve --live-billing
Step Functions definitions are shown automatically when a state machine node is selected. Recent execution summaries are loaded from a button in the State Machine panel when the viewer has an AWS profile.
Helps set up an AWS Organizations-compatible read-only role flow for scanning.
stackmap version
Prints the installed StackMap version.
Interactive UI Features
When you open the StackMap UI, you get:
architecture graph rendering
service-specific nodes and AWS-aware icons
relationship lines and animated flows
graph grouping
search
filter sidebar
detail panel
Step Functions workflow panel for state-machine nodes
keyboard shortcuts
timeline / diff controls
edit mode
Advanced insight panels
Smart grouping
Smart grouping is currently applied automatically during stackmap serve unless you disable it with --no-auto-group.
For live AWS scans, StackMap also applies a live-account grouping pass during scan assembly. That pass uses tags and inferred service relationships before falling back to network-level context.
The grouping engine prioritizes:
environment, account, and region scopes when a graph spans multiple boundaries
business tags such as service, app, project, component, workload, and team/owner labels
Terraform module paths and CloudFormation/SAM stack membership
shared IAM roles for compute resources
naming-family fallback with normalized resource-name tokenization
VPC or subnet grouping only as a fallback
connected components when no stronger grouping signal exists
Earlier strategies win, so a CloudFormation/SAM or business-tagged application cluster is preferred over a lower-signal VPC bucket. This keeps the UI focused on business components first and infrastructure topology second.
Auto-generated groups include metadata such as grouping strategy, confidence, reason, signals, parent group, account IDs, regions, and resource counts by type. The component landing page shows reason captions, confidence pips, parent-scope filter chips, and a View All option. Resources that no smart group claims are collected in an unlinked bucket instead of being mixed into the main component list.
See docs/smart-groups.md for grouping examples and tuning notes.
Step Functions viewer
State machine definitions are parsed into a structured ASL graph when StackMap sees them in Terraform, CloudFormation/SAM, or live AWS scans. The detail panel renders a state-machine section with Task, Choice, Parallel, Map, Wait, Pass, Succeed, and Fail states, warnings for unreachable or malformed flows, and a raw ASL graph toggle.
Recent execution summaries are loaded on demand from the State Machine panel. Click Load recent executions while serving with an AWS profile:
stackmap scan-aws --profile dev --serve
For already-created JSON graphs, serve with a profile:
stackmap serve --source aws-output.json --aws-profile dev
The button calls states:ListExecutions only when clicked. Without that permission, the workflow diagram still works and the viewer shows a clear message for execution history.
Clicking a resolved Task resource in the state-machine viewer selects and pans the main graph to that resource. See docs/step-functions.md for the ASL graph contract and manual review checklist.
Relationship evidence and architecture inference
Live AWS scans attach evidence metadata to inferred relationships whenever possible.
The UI surfaces this in the edge detail panel so users can see why an edge exists instead of treating generated architecture as a black box.
Default architecture views prioritize functional relationships such as triggers, routes_to, reads_from, writes_to, and cross_account_reference. Lower-signal relationship types such as generic references, IAM/auth edges, and network reachability context remain available for inspection and filtering without overwhelming the main architecture view.
Cost forecasting
The cost panel in the UI is a forecast overlay by default. It becomes billing-aware only when live billing is explicitly enabled.
Current behavior:
StackMap computes a baseline monthly estimate from resource metadata and bundled pricing heuristics
the top-right cost panel shows total forecast plus top components and category totals
the detail panel lets you add resource-level usage inputs such as Lambda memory, invocations, duration, storage GB, and transfer GB
when you add inputs, StackMap recomputes the estimate and shows the delta from the baseline forecast
Optional live usage import:
With --live-billing, StackMap can pull AWS Cost Explorer totals and CloudWatch usage metrics for supported services, then recalculate the forecast from those usage inputs.
Without --live-billing, the UI stays on local heuristic forecasting and never calls AWS billing or CloudWatch metrics APIs.
Supported usage imports include Lambda invocations/duration, S3 storage and transfer-related metrics where available, DynamoDB/SQS-style service metrics where mapped, and CloudFront BytesDownloaded for replacing the default 100 GB transfer assumption.
Live CloudWatch logs
Live logs are optional and only run when you explicitly enable them:
stackmap scan-aws --profile dev --serve --live-logs
This keeps the default AWS scan on the minimal read-only policy. If your AWS profile also has the separate live logs policy attached, the UI shows a Live logs toggle in the Insights panel and a View CloudWatch logs button for supported resources in the detail panel.
The log panel can fetch the last hour, 6 hours, 24 hours, or 7 days, and can aggregate logs from all currently visible resources in the graph.
The live logs policy is separate from the normal scan policy so teams can review and attach it only when they want CloudWatch log access:
stackmap aws-policy --addon logs
The packaged policy file is also available for review at stackmap/cli/aws_policy_live_logs.json.
AWS billing and usage imports
AWS billing is also optional and separate from the default scan policy:
stackmap scan-aws --profile dev --serve --live-billing
When enabled, the Cost & Usage panel can fetch AWS usage metrics for all supported resources and recalculate the forecast. Individual resources can also fetch their own usage from the detail panel. CloudFront distributions use the CloudWatch BytesDownloaded metric to replace the default transfer estimate when available.
The billing policy is separate from the normal scan policy:
stackmap aws-policy --addon billing
Step Functions workflow graph and execution debugging
State machine definitions are parsed during normal Terraform, CloudFormation/SAM, and live AWS scans. Select a Step Functions node and click Open workflow graph to switch the main canvas into a StackMap-style workflow view with ASL states, labeled paths, warnings, and an optional Show target resources toggle for resolved Task targets.
Workflow structure uses the normal scan permissions:
states:ListStateMachines
states:DescribeStateMachine
Execution debugging is deliberately on demand. Load recent executions requires states:ListExecutions; selecting one execution and applying the per-state overlay requires states:GetExecutionHistory. StackMap does not fetch execution histories automatically.
Attach the optional debugger policy only when you want execution overlays:
stackmap aws-policy --addon stepfunctions
Drift detection
Drift detection is enabled by serving one graph against another:
Create and publish a GitHub Release tag in vX.Y.Z format.
Wait for workflows Homebrew Release and Windows Release to complete.
macOS users can then run:
brew upgrade stackmap
Windows users can then run:
winget upgrade ZiadElraggal.StackMap
Project Direction
StackMap is evolving into a hybrid of:
infrastructure scanner
architecture inference engine
multi-account mapper
interactive explorer
architecture correction and presentation tool
The product direction is intentionally:
generated-first
reality-based
CLI-first
presentation-friendly
Troubleshooting
stackmap command not found after install
Run:
brew doctor
brew --prefix
stackmap version
If installed from source, make sure your virtual environment is active or the install location is on your PATH.
Homebrew release does not show latest UI changes
Recent releases now build the packaged frontend in CI before publishing the release artifact used by Homebrew. If a just-published release is not yet available, wait for the Homebrew Release workflow to finish and then try:
brew upgrade stackmap
AWS scan permissions
If a live AWS scan fails due to missing permissions, use:
stackmap aws-policy
to generate a read-only policy template for scanning.
Optional live UI features use separate policies that can be reviewed and attached independently: