Generated Documentation

Generated documentation should be a projection from deterministic deployment artifacts, not hand-maintained topology.

The current infra topology implementation is described in Infra Topology Processing.

Current Flow

1. Capture raw Pulumi outputs, exports, DOT graphs, workflow identity, and deploy telemetry as private artifacts.
2. Project selected structural metadata into sanitized review candidates.
3. Render selected raw graph formats into private human-review artifacts.
4. Normalize selected data into a compact graph schema with environment, provider, stack, commit, nodes, and edges.
5. Attach Wavemap semantic metadata for meaningful architecture boundaries.
6. Generate focused Mermaid diagram candidates and candidate manifests.
7. Record human figure-slot decisions in the sanitized review ledger.
8. Publish only approved SVG figures and reviewed source sidecars into curated docs pages.

Public Docs Boundary

The docs app should consume reviewed diagrams, summaries, and inventories. It should not publish raw Pulumi exports, live AWS inventory, secret-adjacent values, or low-value provider noise.

Sanitized Projections

Sanitized projections should use structural allowlists instead of trying to maintain a list of every possible secret key. The first resource inventory projection may keep Pulumi type, logical name, environment, provider adapter, hash-derived inventory identity, and review status. It should not copy Pulumi inputs, outputs, physical provider IDs, dependency payloads, provider payloads, or arbitrary provider-specific fields.

Unresolved fields should stay honest: unclassified, unassigned, null, or empty arrays are acceptable review states. Generated docs should not invent dummy values for secrets, resource identities, lifecycle classes, diagram anchors, or documentation targets.

Normalized Graphs

The normalized graph is the private root dataset for generated topology work. It should be projected from sanitized data, not raw Pulumi exports or raw provider payloads, and should keep provider-neutral vocabulary in front of provider-specific implementation details.

The first graph shape may include environment profile, provider adapter, and provider resource nodes. Later projections can add assemblies, components, dependency edges, docs slots, and lifecycle classes after those facts have reviewed metadata. This lets the docs generate both low-level resource views and higher-level architecture diagrams without publishing raw cloud evidence.

Visualization generators should consume the normalized graph rather than provider-specific raw captures. Cloud-specific facts should arrive through adapters, while stable output contracts use Wavemap concepts such as environment profiles, assemblies, components, runtime boundaries, data boundaries, and documentation targets.

Each graph should record its determinism contract. Stable graph identity and topology hashes should exclude transient capture metadata such as generation time while preserving sorted nodes, sorted edges, stable edge IDs, and enough source identity to compare reviewed projections.

Dependency edges need a typed projection layer. The first normalized graph should keep only conservative structural edges, such as environment-to-provider-adapter and provider-adapter-to-resource relationships. Raw DOT/SVG output can remain private debug evidence, but provider-specific dependency parsing should not become public documentation or canonical graph data until it has a tested, provider-neutral projection contract.

Private Visualizations

Pulumi DOT renders can help humans inspect resource dependency shape quickly, but they are not the canonical graph model. Rendered DOT SVGs may preserve raw Pulumi labels and should stay private review artifacts until a human decides whether a sanitized derivative belongs in a curated docs slot.

Architecture diagrams should usually be generated from normalized graph data plus reviewed semantic metadata rather than directly from the raw Pulumi DOT render. Useful views include assembly overviews, focused runtime/data-flow diagrams, and drill-down diagrams that connect leaf provider resources back to the system assembly they implement.

Published Generated Assets

The first approved generated topology figures are public curated docs assets:

• Documentation deployment topology.
• Deployed-dev application topology.

The public pages use SVG for presentation and keep reviewed Mermaid source sidecars beside the figures. Raw captures, private Mermaid candidates, candidate manifests, and workflow evidence remain outside the public docs site.

Deferred

• Automated generated topology publication.
• D2 or another publication-polish renderer.
• Historical topology snapshots.
• Drift reports.
• Interactive graph views.