Technical architecture based on arc42 documentation standard. Clean separation, extensible design, security-first.
tfplan2md converts Terraform plan JSON into Markdown reports optimized for pull request reviews.
Terraform Plan JSON
terraform show -json
Parse · Transform · Render
Markdown Report
GitHub / Azure DevOps PR
Mask sensitive values by default · FROM scratch container · AOT-compiled static binary · Non-root user (UID 1654) · No shell · Minimal attack surface
Handle malformed JSON gracefully · Validate all markdown output · Comprehensive test coverage
Simple CLI · Sensible defaults · Clear error messages · Zero configuration needed
Clean architecture · Immutable models · Pure functions · Modern C# patterns
Custom templates · Resource-specific renderers · Provider-specific handling
Fast startup for CI/CD · Handle large plans efficiently · 14.7MB Docker image (89.6% reduction) · AOT compilation with aggressive trimming
Clean separation of concerns with immutable data models and pure transformation functions.
Command-line parsing and orchestration. Handles user input, loads configuration, coordinates workflow.
CliParser.cs
HelpTextProvider.cs
Terraform plan JSON parsing into immutable domain models using System.Text.Json.
TerraformPlan.cs
TerraformPlanParser.cs
Transform domain models into report models. Build resource summaries, group by module, apply inline diffing.
ReportModel.cs
Summaries/*.cs
Apply Scriban templates to generate markdown. Supports default templates, summary template, and custom user templates.
MarkdownRenderer.cs
ScribanHelpers.cs
Templates/*.sbn
Azure-specific functionality: principal ID mapping, resource ID parsing, role assignment formatting.
PrincipalMapper.cs
azurerm/* templates
Sensitive value detection and masking. AOT-compiled static binary in FROM scratch container. Non-root user, no shell, minimal dependencies.
--show-sensitive flag
FROM scratch + 3 musl libs
All data models are immutable records. No mutable shared state. Pure functions for transformations.
Default templates embedded as resources. Custom templates from filesystem. Resource-specific overrides.
Clear boundaries: Parsing → Model Building → Rendering. Each component has single responsibility.
Sensitive values masked unless explicitly shown. FROM scratch containers with AOT-compiled static binaries. Non-root user, no shell, minimal dependencies.
Key technical decisions and architectural patterns that shape tfplan2md. These guide consistent implementation across features.
Lightweight, text-focused template engine with familiar syntax. Better fit than Razor or Liquid for markdown generation. Embeddable, supports custom functions, and works seamlessly with AOT compilation.
Ahead-of-time compilation produces static native executable (linux-musl-x64). Deployed in FROM scratch container with only 3 musl libraries. Achieves 14.7MB image size (89.6% reduction from baseline) with fastest possible startup time.
Records for immutable data models, file-scoped namespaces, nullable reference types, pattern matching. Comprehensive XML documentation (including private members) for AI-assisted development.
CSS @layer directive isolates rendered example styles from website page styles. Examples use
@layer examples with lower cascade priority than website styles.
Complex resources (firewall rules, NSG rules, role assignments, variable groups) use specialized templates with ViewModel pattern. C# Factory precomputes semantic diffs, matches items by key (e.g., rule name), formats before/after comparisons.
Direct template dispatch replaces render-then-replace pattern. Main template orchestrates with composable partials
(_header.sbn, _resource.sbn, _footer.sbn). Resource-specific templates override default partial.
include with custom template loader.
Standalone HtmlRenderer tool converts markdown to HTML with GitHub and Azure DevOps flavors. Uses Markdig
with platform-specific pipelines. GitHub strips style attributes; Azure DevOps preserves for theme support.
{{content}} placeholder.
Not pixel-perfect but "good enough approximation" for development workflows.
ScreenshotGenerator tool uses Playwright + Chromium for automated screenshot capture. Supports full-page capture, element targeting by Terraform resource address or CSS selector, multiple formats (PNG/JPEG).
Optional diagnostics collected throughout pipeline via DiagnosticContext passed to components.
Single --debug flag appends section showing principal mapping status, template resolution, failed ID lookups.
Every report includes metadata line: tfplan2md version, git commit hash (7 chars), generation timestamp UTC, Terraform version.
Format: Generated by tfplan2md X.Y.Z (abc1234) on YYYY-MM-DD HH:MM:SS UTC | Terraform 1.x.x
--hide-metadata flag.
Modern test framework with true async support, real-time progress reporting, parallel execution. Comprehensive test coverage (unit, integration, snapshot) with fast feedback loops.
Development script generates plan JSON from config + state without terraform plan execution.
Constructs synthetic plan structure for rapid iteration on resource-specific templates.
This page provides a high-level overview. For complete details including building block views, runtime scenarios, deployment architecture, and design decisions, see the full arc42 documentation.