Infra Topology Processing

Infra topology processing turns deployment evidence into reviewed docs assets without publishing raw cloud state.

The pipeline is deliberately staged. Each stage narrows the data surface, records the contract it produced, and keeps a human review gate between private generated artifacts and public documentation.

Pipeline Stages

Stage	Command family	Output	Publication posture
Raw capture	wavemap infra topology capture	Pulumi outputs, exports, DOT graph, and capture manifest.	Private only.
Sanitized inventory	wavemap infra topology project-inventory	Hash-backed resource inventory with structural allowlists.	Private review input.
DOT render	wavemap infra topology render-dot	Rendered Pulumi graph and render manifest.	Private debug evidence.
Normalized graph	wavemap infra topology project-graph	Provider-neutral graph with environment, adapter, resource nodes, and deterministic identity.	Private review input.
Semantic diagram	wavemap infra topology project-diagram	Focused Mermaid candidate plus candidate manifest.	Private Static figure and candidate until reviewed.
Figure publication	Human ledger decision plus curated docs edit	reviewed Mermaid source sidecar.	Public only after approval.

The trunk CLI exposes the route family, but the typed projections live in @wavemap/operations. Shell wrappers own the live Pulumi calls, filesystem staging, and private artifact paths.

For public route metadata, compatibility scripts, wrapper paths, key flags, and default mutation posture, use the Infra Topology command reference.

Code Entry Points

File	Hook
packages/cli/src/wavemap-cli/helpers/routes/infra-topology.ts	Public wavemap infra topology ... route table.
bin/infra-topology/capture-raw-pulumi-artifacts.sh	Live Pulumi capture wrapper.
bin/infra-topology/project-sanitized-resource-inventory.sh	Sanitized inventory wrapper.
bin/infra-topology/render-pulumi-dot-graph.sh	Private DOT render wrapper.
bin/infra-topology/project-normalized-infra-graph.sh	Normalized graph wrapper.
bin/infra-topology/project-semantic-mermaid-diagram.sh	Private semantic Mermaid candidate wrapper.
infra/operations/src/infra-topology/register-cli.ts	Registers the typed infra-topology operations subcommands.
infra/operations/src/infra-topology/contracts/v1.ts	Versioned topology artifact contracts.
infra/topology-processing-reviews/figure-slot-decisions.json	Sanitized human publication ledger.

The operations CLI composes the typed stage commands in one place:

registerWriteRawCaptureManifestCommand(infraTopologyCommand, runtime)
registerWritePulumiDotRenderManifestCommand(infraTopologyCommand, runtime)
registerProjectSanitizedResourceInventoryCommand(infraTopologyCommand, runtime)
registerProjectNormalizedInfraGraphCommand(infraTopologyCommand, runtime)
registerProjectSemanticMermaidDiagramCommand(infraTopologyCommand, runtime)

The shell wrappers stay thin. For example, the semantic diagram wrapper requires pnpm, checks the typed operations entrypoint, strips passthrough -- markers, and delegates:

pnpm --silent -C "$OPERATIONS_DIR" infra-topology:project-diagram -- "$@"

That split keeps live process control in shell and deterministic projection logic in TypeScript.

The manual .github/workflows/infra-topology-ingest.yml path reads Pulumi through the self-managed S3 backend, not Pulumi Cloud. Its GitHub dev environment contract is intentionally infra-operator scoped:

• PULUMI_BACKEND_URL selects the S3 backend.
• PULUMI_STATE_BACKEND_AWS_REGION selects the AWS region for backend access.
• INFRA_TOPOLOGY_AWS_ROLE_TO_ASSUME grants backend access through GitHub OIDC.
• PULUMI_CONFIG_PASSPHRASE decrypts the Pulumi stack state.

These values are not routine app/API or docs CD inputs.

Stage Hooks

Useful local entry points mirror the pipeline:

pnpm wavemap -- infra topology capture
pnpm wavemap -- infra topology project-inventory -- --raw-capture-dir private/infra-topology/raw-capture
pnpm wavemap -- infra topology project-graph -- --sanitized-inventory-json private/infra-topology/sanitized-resource-inventory.json
pnpm wavemap -- infra topology project-diagram -- --normalized-graph-json private/infra-topology/normalized-infra-graph.json --diagram-candidate-manifest-json private/infra-topology/diagram-candidate-manifest.json

The typed operation subcommands expose the lower-level file contracts. For example:

infra-topology project-inventory
  --raw-capture-dir <path>
  --output-json <path>
  --github-output

infra-topology project-graph
  --sanitized-inventory-json <path>
  --dependency-edge-projection-json <path>
  --reviewed-topology-metadata-json <path>
  --output-json <path>

infra-topology project-diagram
  --normalized-graph-json <path>
  --diagram-candidate-manifest-json <path>
  --output-mermaid <path>
  --manifest-json-out <path>

These flags are the best hooks for tests, local reproduction, and CI artifact plumbing because they make inputs and outputs explicit.

Privacy Boundary

Raw topology artifacts can contain provider-specific details that are useful for debugging and unsuitable for docs. The public docs boundary is based on these rules:

• Do not publish raw Pulumi exports, raw DOT labels, provider physical IDs, arbitrary inputs or outputs, workflow evidence, or local operator notes.
• Prefer structural allowlists over denylisting secret-looking keys.
• Use hash-derived identities where a stable join key is needed.
• Preserve unresolved states honestly with values such as unclassified, unassigned, or null.
• Publish only reviewed, sanitized projections into curated docs pages or static docs assets.

This means a generated diagram can be valuable before it is publishable. Private candidates are expected to be reviewed, accepted, rejected, or superseded rather than copied directly into docs.

Semantic Review

The normalized graph is intentionally low-level. Reviewed topology metadata adds Wavemap-specific meaning such as:

• Environment profile.
• Assembly.
• Component.
• Lifecycle class.
• Documentation targets.
• Diagram anchors.

This metadata lets diagrams speak in system concepts like public web surface, runtime, media storage, static origin, and control plane instead of provider resource names.

The metadata is intentionally separate from raw capture. A reviewed resource classification can be changed without changing the provider state capture that it annotates.

Figure Ledger

Publication decisions are recorded in infra/topology-processing-reviews/figure-slot-decisions.json.

Each decision records:

• The docs page and section slot where the figure belongs.
• The durable figure ID.
• The candidate ID and stable topology hash being reviewed.
• The human decision and notes.
• Whether the result is approved for public docs publication.
• The promoted SVG path and reviewed Mermaid source path when publication is approved.

Keeping old rejected or private-review decisions in the ledger is intentional. The ledger is a history of human review, not only a pointer to the latest public figure.

An approved publication entry looks like this shape:

{
  "decision": {
    "status": "accepted",
    "notes": ["Approved the reviewed diagram for publication."]
  },
  "publication": {
    "publicDocsReady": true,
    "replacementApproved": true,
    "status": "approved-for-publication",
    "promotedDocsPath": "apps/wavemap-docs/src/content/docs/operations/deployment.md#fig-dev-application-deployment",
    "promotedAssetPath": "apps/wavemap-docs/src/content/docs/figures/topology/fig-dev-application-deployment.svg",
    "promotedSourcePath": "apps/wavemap-docs/public/operations/figures/topology/fig-dev-application-deployment.mmd"
  }
}

The ledger should never point at private generated artifacts as public promoted paths.

Published Assets

The first public topology figures are:

• Docs Hosting: documentation deployment topology.
• Deployment: deployed-dev application topology.

The docs pages use SVG for stable presentation. Reviewed Mermaid source is published as a sidecar when it is useful to inspect the generated source, while raw private candidates remain outside the docs site.

The docs page pattern uses a content-local SVG so editor previews can load it and Astro can optimize it:

![Topology diagram showing the dev application public web surface, control plane, runtime, media storage, and image registry relationships.](../figures/topology/fig-dev-application-deployment.svg)

_Reviewed Mermaid source:
[fig-dev-application-deployment.mmd](../figures/topology/fig-dev-application-deployment.mmd)._

Known Limits

The current app topology diagram shows the Pulumi-visible deployed-dev surface. Runtime database and volume state are not yet modeled as separate provider-neutral topology nodes.

Future Scope

Likely next improvements are:

• Model runtime database and volume state as separate provider-neutral topology nodes.
• Add provider adapter contracts before adding non-AWS capture sources.
• Generate a route or docs index of available topology artifacts from manifests and ledger entries.
• Add automated checks that approved publication paths exist and are referenced from the target docs page.
• Add richer semantic graph views for data boundaries, runtime dependencies, and deployable surfaces.
• Add drift reports comparing stable topology hashes across captures.
• Add historical snapshots only after there is a clear operator question they answer.
• Consider graph database import for local topology queries after the normalized graph contract stabilizes.
• Add docs smoke checks for promoted figure assets and Mermaid source sidecars.