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

Clone and install:

git clone https://github.com/ziadelraggal/stackmap.git
cd stackmap
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

Verify:

stackmap version
stackmap --help

Windows: winget

Install via winget:

winget install ZiadElraggal.StackMap

Verify install:

stackmap version
stackmap --help

Update:

winget upgrade ZiadElraggal.StackMap

Uninstall:

winget uninstall ZiadElraggal.StackMap

New releases are automatically submitted to the winget package repository when a GitHub Release is published, just like Homebrew.

Quick Start

1. Scan a Terraform state file

stackmap scan --source terraform.tfstate --format json --output stackmap-output.json

Or generate an interactive HTML output:

stackmap scan --source terraform.tfstate --format html --output stackmap-output.html

2. Serve the interactive UI locally

stackmap serve --source terraform.tfstate

Serve with drift detection against a second source:

stackmap serve --source terraform.tfstate --drift-against aws-live.json

If stackmap-output.json already exists, you can also serve that:

stackmap serve --source stackmap-output.json

3. Scan an entire repository

stackmap scan-repo . --output stackmap-repo-output.json

4. Scan live AWS infrastructure

Single account / profile:

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.

Multi-account via named profiles:

stackmap scan-aws --account-profiles dev,sandbox --output multi.json --serve

Multi-account via explicit role assumption:

stackmap scan-aws \
  --accounts 'dev:arn:aws:iam::111122223333:role/StackMapReadOnly,sandbox:arn:aws:iam::444455556666:role/StackMapReadOnly' \
  --output multi.json \
  --serve

5. Compare two infrastructure snapshots

stackmap diff before.json after.json --output stackmap-diff.json

Main CLI Commands

`stackmap scan`

Parses a single infrastructure source and produces JSON or HTML output.

Use this for:

Terraform state files
CloudFormation JSON
other directly supported source files

`stackmap scan-repo`

Discovers infrastructure sources across a repository, merges them, and produces a unified graph.

Use this when:

infrastructure is spread across multiple directories
you want repo-level architecture visibility
you want Terraform, CloudFormation, and SAM discovered together

`stackmap scan-aws`

Scans live AWS infrastructure through read-only APIs.

Use this for:

current-state architecture maps
multi-account visibility
environments that are not fully represented in code snippets alone
relationship inference from live AWS configuration
Step Functions workflow parsing from live state-machine definitions
optional live logs and billing-aware usage imports when explicitly enabled
on-demand recent Step Functions executions from the State Machine panel when served with a profile

`stackmap serve`

Launches the interactive local web UI for exploring a graph.

Use this when:

you want the full StackMap experience
you want editing, filtering, or presentation workflows
you want to inspect large graphs interactively

Useful options:

--drift-against compares the served graph against another snapshot and enables drift badges in the UI
--auto-group/--no-auto-group controls smart grouping during serve
--aws-profile enables on-demand AWS-backed detail actions such as recent Step Functions executions
--aws-profile --live-logs enables the CloudWatch log viewer for locally served graphs when the profile has the separate logs policy
--aws-profile --live-billing enables AWS billing and CloudWatch usage metric imports when the profile has the separate billing policy

`stackmap diff`

Computes a diff between two infrastructure snapshots and outputs a graph with change metadata.

`stackmap org-import`

Imports / overlays organization data for AWS organization-aware views.

`stackmap aws-policy`

Builds AWS IAM policy documents for StackMap.

By default it prints the base read-only scan policy:

stackmap aws-policy

Optional live features are separate add-on policies, not part of the default scan policy:

stackmap aws-policy --addon logs
stackmap aws-policy --addon billing
stackmap aws-policy --addon stepfunctions

`stackmap setup-org-role`

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.

Example edge metadata:

{
  "source": "aws_live_inference",
  "inference_rule": "apigateway_lambda_integration_uri",
  "confidence": "high",
  "evidence": "API Gateway integration URI references arn:aws:lambda:us-east-1:123456789012:function:orders-handler",
  "api_calls": ["apigateway:get_integration"]
}

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:

stackmap serve --source desired.json --drift-against live.json

Current behavior:

StackMap normalizes both graphs into a shared comparison model
it matches resources across the two graphs
it compares a curated set of important properties for known resource types
it compares relationships to detect missing or extra connections
it annotates the served IR so the UI can show resource badges and summary counts

Unknown resource types fall back to a broader property comparison with unstable keys such as IDs, ARNs, and timestamps ignored.

Edit mode details

Edit mode is intended as a correction layer over real infrastructure, not a fully manual diagram editor.

Current edit capabilities:

Inspect mode for safe browsing
Structure mode for layer moves, hide/show, and architecture cleanup
Connect mode for manual relationships
custom nodes and custom links
layer management
node reordering within a lane
presentation cleanup workflows

Edits are currently persisted locally in the browser and can also be exported/imported as edit overlay JSON.

Typical Workflows

Generate from Terraform and present it

stackmap scan --source terraform.tfstate --format json --output stackmap-output.json
stackmap serve --source stackmap-output.json

Then in the UI:

hide noisy resources
add any missing links
tidy the architecture layout
switch to presentation mode

Understand a large repository

stackmap scan-repo . --output stackmap-repo-output.json
stackmap serve --source stackmap-repo-output.json

Then:

use component landing view
isolate components / layers
filter relationships
navigate the architecture incrementally

Map multiple AWS accounts

stackmap scan-aws --account-profiles dev,sandbox,shared --output org.json --serve

Then:

inspect account groupings
look for cross-account links
focus only the portion of the system you want to present

Output Formats

JSON

Useful for:

automation
testing
feeding the interactive viewer
product demos / scripted website demos

HTML

Useful for:

sharing architecture snapshots
lightweight presentation artifacts
generated outputs without running the local dev UI

Development

Contributor setup

make install-dev

Helpful commands

Build frontend static assets:

make frontend-build

Sync generated frontend assets into the packaged Python web bundle:

make sync-webapp-assets

Build the Python package:

make package-build

Run tests:

make test

Lint:

make lint

Format:

make format

Packaging and Release Flow

Homebrew release automation

On GitHub Release publish (vX.Y.Z), the Homebrew Release workflow:

Builds the frontend static app from the tagged source.
Syncs generated assets into the Python package bundle.
Creates a release source archive and uploads it to the GitHub Release.
Computes the archive SHA256 and renders a stable stackmap.rb formula.
Uploads the formula as a workflow artifact.
Pushes the formula update to the Homebrew tap if configured.

Windows / winget release automation

On GitHub Release publish (vX.Y.Z), the Windows Release workflow:

Builds the frontend static app from the tagged source.
Syncs generated assets into the Python package bundle.
Installs StackMap plus PyInstaller on windows-latest.
Builds a standalone stackmap.exe and uploads it to the GitHub Release.
Uses wingetcreate to automatically submit an updated manifest PR to microsoft/winget-pkgs.

You can also run the workflow manually from Actions to generate a Windows artifact before cutting a public release.

Required GitHub configuration for automatic releases

repository variable: HOMEBREW_TAP_REPO
- example: ziadelraggal/homebrew-stackmap
repository secret: HOMEBREW_TAP_TOKEN
- token with push access to that tap repo
repository secret: WINGET_PAT
- a GitHub PAT with public_repo scope, used by wingetcreate to fork microsoft/winget-pkgs and open manifest update PRs

Release flow

Bump version in pyproject.toml.
Merge to main.
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:

stackmap aws-policy --addon logs
stackmap aws-policy --addon billing
stackmap aws-policy --addon stepfunctions

The same reviewable JSON files are included in the package:

stackmap/cli/aws_policy.json
stackmap/cli/aws_policy_live_logs.json
stackmap/cli/aws_policy_billing.json
stackmap/cli/aws_policy_stepfunctions.json

License

MIT

StackMap

Architecture diagrams that generate themselves from your infrastructure code and live AWS accounts.

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

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

Clone and install:

git clone https://github.com/ziadelraggal/stackmap.git
cd stackmap
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

Verify:

stackmap version
stackmap --help

Windows: winget

Install via winget:

winget install ZiadElraggal.StackMap

Verify install:

stackmap version
stackmap --help

Update:

winget upgrade ZiadElraggal.StackMap

Uninstall:

winget uninstall ZiadElraggal.StackMap

New releases are automatically submitted to the winget package repository when a GitHub Release is published, just like Homebrew.

Quick Start

1. Scan a Terraform state file

stackmap scan --source terraform.tfstate --format json --output stackmap-output.json

Or generate an interactive HTML output:

stackmap scan --source terraform.tfstate --format html --output stackmap-output.html

2. Serve the interactive UI locally

stackmap serve --source terraform.tfstate

Serve with drift detection against a second source:

stackmap serve --source terraform.tfstate --drift-against aws-live.json

If stackmap-output.json already exists, you can also serve that:

stackmap serve --source stackmap-output.json

3. Scan an entire repository

stackmap scan-repo . --output stackmap-repo-output.json

4. Scan live AWS infrastructure

Single account / profile:

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

Multi-account via named profiles:

stackmap scan-aws --account-profiles dev,sandbox --output multi.json --serve

Multi-account via explicit role assumption:

stackmap scan-aws \
  --accounts 'dev:arn:aws:iam::111122223333:role/StackMapReadOnly,sandbox:arn:aws:iam::444455556666:role/StackMapReadOnly' \
  --output multi.json \
  --serve

5. Compare two infrastructure snapshots

stackmap diff before.json after.json --output stackmap-diff.json

Main CLI Commands

`stackmap scan`

Parses a single infrastructure source and produces JSON or HTML output.

Use this for:

Terraform state files
CloudFormation JSON
other directly supported source files

`stackmap scan-repo`

Discovers infrastructure sources across a repository, merges them, and produces a unified graph.

Use this when:

infrastructure is spread across multiple directories
you want repo-level architecture visibility
you want Terraform, CloudFormation, and SAM discovered together

`stackmap scan-aws`

Scans live AWS infrastructure through read-only APIs.

Use this for:

current-state architecture maps
multi-account visibility
environments that are not fully represented in code snippets alone
relationship inference from live AWS configuration
Step Functions workflow parsing from live state-machine definitions
optional live logs and billing-aware usage imports when explicitly enabled
on-demand recent Step Functions executions from the State Machine panel when served with a profile

`stackmap serve`

Launches the interactive local web UI for exploring a graph.

Use this when:

you want the full StackMap experience
you want editing, filtering, or presentation workflows
you want to inspect large graphs interactively

Useful options:

--drift-against compares the served graph against another snapshot and enables drift badges in the UI
--auto-group/--no-auto-group controls smart grouping during serve
--aws-profile enables on-demand AWS-backed detail actions such as recent Step Functions executions
--aws-profile --live-logs enables the CloudWatch log viewer for locally served graphs when the profile has the separate logs policy
--aws-profile --live-billing enables AWS billing and CloudWatch usage metric imports when the profile has the separate billing policy

`stackmap diff`

Computes a diff between two infrastructure snapshots and outputs a graph with change metadata.

`stackmap org-import`

Imports / overlays organization data for AWS organization-aware views.

`stackmap aws-policy`

Builds AWS IAM policy documents for StackMap.

By default it prints the base read-only scan policy:

stackmap aws-policy

Optional live features are separate add-on policies, not part of the default scan policy:

stackmap aws-policy --addon logs
stackmap aws-policy --addon billing
stackmap aws-policy --addon stepfunctions

`stackmap setup-org-role`

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

See docs/smart-groups.md for grouping examples and tuning notes.

Step Functions viewer

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.

Example edge metadata:

{
  "source": "aws_live_inference",
  "inference_rule": "apigateway_lambda_integration_uri",
  "confidence": "high",
  "evidence": "API Gateway integration URI references arn:aws:lambda:us-east-1:123456789012:function:orders-handler",
  "api_calls": ["apigateway:get_integration"]
}

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.

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

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

The billing policy is separate from the normal scan policy:

stackmap aws-policy --addon billing

Step Functions workflow graph and execution debugging

Workflow structure uses the normal scan permissions:

states:ListStateMachines
states:DescribeStateMachine

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:

stackmap serve --source desired.json --drift-against live.json

Current behavior:

StackMap normalizes both graphs into a shared comparison model
it matches resources across the two graphs
it compares a curated set of important properties for known resource types
it compares relationships to detect missing or extra connections
it annotates the served IR so the UI can show resource badges and summary counts

Unknown resource types fall back to a broader property comparison with unstable keys such as IDs, ARNs, and timestamps ignored.

Edit mode details

Edit mode is intended as a correction layer over real infrastructure, not a fully manual diagram editor.

Current edit capabilities:

Inspect mode for safe browsing
Structure mode for layer moves, hide/show, and architecture cleanup
Connect mode for manual relationships
custom nodes and custom links
layer management
node reordering within a lane
presentation cleanup workflows

Edits are currently persisted locally in the browser and can also be exported/imported as edit overlay JSON.

Typical Workflows

Generate from Terraform and present it

stackmap scan --source terraform.tfstate --format json --output stackmap-output.json
stackmap serve --source stackmap-output.json

Then in the UI:

hide noisy resources
add any missing links
tidy the architecture layout
switch to presentation mode

Understand a large repository

stackmap scan-repo . --output stackmap-repo-output.json
stackmap serve --source stackmap-repo-output.json

Then:

use component landing view
isolate components / layers
filter relationships
navigate the architecture incrementally

Map multiple AWS accounts

stackmap scan-aws --account-profiles dev,sandbox,shared --output org.json --serve

Then:

inspect account groupings
look for cross-account links
focus only the portion of the system you want to present

Output Formats

JSON

Useful for:

automation
testing
feeding the interactive viewer
product demos / scripted website demos

HTML

Useful for:

sharing architecture snapshots
lightweight presentation artifacts
generated outputs without running the local dev UI

Development

Contributor setup

make install-dev

Helpful commands

Build frontend static assets:

make frontend-build

Sync generated frontend assets into the packaged Python web bundle:

make sync-webapp-assets

Build the Python package:

make package-build

Run tests:

make test

Lint:

make lint

Format:

make format

Packaging and Release Flow

Homebrew release automation

On GitHub Release publish (vX.Y.Z), the Homebrew Release workflow:

Builds the frontend static app from the tagged source.
Syncs generated assets into the Python package bundle.
Creates a release source archive and uploads it to the GitHub Release.
Computes the archive SHA256 and renders a stable stackmap.rb formula.
Uploads the formula as a workflow artifact.
Pushes the formula update to the Homebrew tap if configured.

Windows / winget release automation

On GitHub Release publish (vX.Y.Z), the Windows Release workflow:

Builds the frontend static app from the tagged source.
Syncs generated assets into the Python package bundle.
Installs StackMap plus PyInstaller on windows-latest.
Builds a standalone stackmap.exe and uploads it to the GitHub Release.
Uses wingetcreate to automatically submit an updated manifest PR to microsoft/winget-pkgs.

You can also run the workflow manually from Actions to generate a Windows artifact before cutting a public release.

Required GitHub configuration for automatic releases

repository variable: HOMEBREW_TAP_REPO
- example: ziadelraggal/homebrew-stackmap
repository secret: HOMEBREW_TAP_TOKEN
- token with push access to that tap repo
repository secret: WINGET_PAT
- a GitHub PAT with public_repo scope, used by wingetcreate to fork microsoft/winget-pkgs and open manifest update PRs

Release flow

Bump version in pyproject.toml.
Merge to main.
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

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:

stackmap aws-policy --addon logs
stackmap aws-policy --addon billing
stackmap aws-policy --addon stepfunctions

The same reviewable JSON files are included in the package:

stackmap/cli/aws_policy.json
stackmap/cli/aws_policy_live_logs.json
stackmap/cli/aws_policy_billing.json
stackmap/cli/aws_policy_stepfunctions.json

License

MIT

StackMap ZiadElraggal

README

StackMap

What StackMap Does

Core Capabilities

Infrastructure scanning and parsing

Interactive architecture UI

Edit and correction mode

Layered architecture model

Multi-account AWS visibility

Live AWS relationship inference

Diff / timeline support

AWS-aware visuals

Installation

Recommended: Homebrew on macOS

Bleeding-edge Homebrew install from source

Install from source

Windows: winget

Quick Start

1. Scan a Terraform state file

2. Serve the interactive UI locally

3. Scan an entire repository

4. Scan live AWS infrastructure

5. Compare two infrastructure snapshots

Main CLI Commands

stackmap scan

stackmap scan-repo

stackmap scan-aws

stackmap serve

stackmap diff

stackmap org-import

stackmap aws-policy

stackmap setup-org-role

stackmap version

Interactive UI Features

Advanced insight panels

Smart grouping

Step Functions viewer

Relationship evidence and architecture inference

Cost forecasting

Live CloudWatch logs

AWS billing and usage imports

Step Functions workflow graph and execution debugging

Drift detection

Edit mode details

Typical Workflows

Generate from Terraform and present it

Understand a large repository

Map multiple AWS accounts

Output Formats

JSON

HTML

Development

Contributor setup

Helpful commands

Packaging and Release Flow

Homebrew release automation

Windows / winget release automation

Required GitHub configuration for automatic releases

Release flow

Project Direction

Troubleshooting

stackmap command not found after install

Homebrew release does not show latest UI changes

AWS scan permissions

License

StackMap ZiadElraggal

README

StackMap

What StackMap Does

Core Capabilities

Infrastructure scanning and parsing

Interactive architecture UI

Edit and correction mode

Layered architecture model

Multi-account AWS visibility

Live AWS relationship inference

Diff / timeline support

AWS-aware visuals

Installation

`stackmap scan`

`stackmap scan-repo`

`stackmap scan-aws`

`stackmap serve`

`stackmap diff`

`stackmap org-import`

`stackmap aws-policy`

`stackmap setup-org-role`

`stackmap version`

`stackmap` command not found after install

`stackmap scan`

`stackmap scan-repo`

`stackmap scan-aws`

`stackmap serve`

`stackmap diff`

`stackmap org-import`

`stackmap aws-policy`

`stackmap setup-org-role`

`stackmap version`

`stackmap` command not found after install