Architecture
Technical architecture based on arc42 documentation standard. Clean separation, extensible design, security-first.
System Overview
tfplan2md converts Terraform plan JSON into Markdown reports optimized for pull request reviews.
Input
Terraform Plan JSON
terraform show -json
tfplan2md
Parse · Transform · Render
Output
Markdown Report
GitHub / Azure DevOps PR
Quality Goals
Security
Mask sensitive values by default · FROM scratch container · AOT-compiled static binary · Non-root user (UID 1654) · No shell · Minimal attack surface · Zero third-party runtime dependencies in the main CLI
Reliability
Handle malformed JSON gracefully · Validate all markdown output · Comprehensive test coverage
Usability
Simple CLI · Sensible defaults · Clear error messages · Zero configuration needed
Maintainability
Clean architecture · Immutable models · Pure functions · Modern C# patterns
Extensibility
Built-in templates · Resource-specific renderers · Provider-specific handling
Performance
Fast startup for CI/CD · Handle large plans efficiently · 2.1 MB Docker image · AOT compilation with aggressive trimming
Core Components
Clean separation of concerns with immutable data models and pure transformation functions.
CLI
Command-line parsing and orchestration. Handles user input, loads configuration, coordinates workflow.
CliParser.cs
HelpTextProvider.cs
Parsing
Terraform plan JSON parsing into immutable domain models using System.Text.Json.
TerraformPlan.cs
TerraformPlanParser.cs
Model Building
Transform domain models into report models. Build resource summaries, group by module, apply inline diffing.
ReportModel.cs
Summaries/*.cs
Rendering
Pure C# renderers generate markdown in a single pass. Built-in report, summary, and resource-specific renderers replace runtime template loading.
MarkdownRenderer.cs
ReportRenderer.cs
ResourceRendererRegistry.cs
Azure Utilities
Azure-specific functionality: principal ID mapping, resource ID parsing, role assignment formatting.
PrincipalMapper.cs
azurerm/* templates
Security
Sensitive value detection and masking. AOT-compiled static binary in a FROM scratch container with no third-party runtime dependencies in the main CLI.
--show-sensitive flag
FROM scratch + UPX-compressed binary
Technology Stack
Architectural Patterns
Immutability
All data models are immutable records. No mutable shared state. Pure functions for transformations.
Renderer-Driven
Built-in renderers generate markdown directly in C#. Resource-specific overrides plug into a shared registry.
Separation of Concerns
Clear boundaries: Parsing → Model Building → Rendering. Each component has single responsibility.
Security by Default
Sensitive values masked unless explicitly shown. FROM scratch containers with AOT-compiled static binaries. Non-root user, no shell, zero third-party runtime dependencies in the main CLI.
Architecture Decision Records
Key technical decisions and architectural patterns that shape tfplan2md. These guide consistent implementation across features.
Pure C# Rendering
Rendering moved out of Scriban templates and into statically typed C# renderer classes. The user-facing template surface is now limited to built-in `default` and `summary` modes.
NativeAOT with FROM scratch
Ahead-of-time compilation produces static native executables for containers and release assets. The main Docker image is now 2.1 MB while keeping the fastest possible startup time.
Modern C# 13 Patterns
Records for immutable data models, file-scoped namespaces, nullable reference types, pattern matching. Comprehensive XML documentation (including private members) for AI-assisted development.
CSS Layers for Website Examples
CSS @layer isolates rendered example styles from website page styles. Examples use @layer examples with lower cascade priority than website styles.
Resource-Specific Renderers with ViewModels
Complex resources (firewall rules, NSG rules, role assignments, variable groups, build definitions) use specialized renderers with ViewModel pattern. C# factories precompute semantic diffs, match items by key, and format before/after comparisons.
Single-Pass Report Rendering
Direct renderer dispatch replaces render-then-replace flows. The main report renderer orchestrates headers, summaries, resources, outputs, and provider overrides in one pass.
Markdig for Platform-Specific HTML
Standalone HtmlRenderer converts markdown to HTML with GitHub and Azure DevOps flavors. GitHub strips style attributes; Azure DevOps preserves them for theme support.
Playwright for Visual Regression
ScreenshotGenerator uses Playwright and Chromium for automated screenshot capture with full-page and targeted element support.
DiagnosticContext for Debug Output
Optional diagnostics are collected throughout the pipeline and appended with a single debug flag.
Report Metadata for Build Traceability
Every report includes tfplan2md version, git commit hash, generation timestamp, and Terraform version metadata.
TUnit for Async-First Testing
Modern test framework with true async support, real-time progress reporting, parallel execution, and comprehensive coverage.
Terraform Show Approximation
Development scripts can generate synthetic plan JSON from config and state without running terraform plan.
Complete Architecture Documentation
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.