pulumi-csa/architecture-diagrams

1. This repository is a documentation/diagram artifact, not the infrastructure itself. Its job is to describe Pulumi-managed production infrastructure in Markdown files containing Mermaid diagrams, so an engineer can understand the system at both stack and whole-environment levels.

2. The repository is organized around two diagram boundaries:

- stacks/ for single-stack views

- master/ for cross-stack, end-to-end overviews

This is the main architectural split in the repo.

3. The production infrastructure is divided into three stacks, each with its own diagram:

- IAM infrastructure

- Network infrastructure

- Cluster infrastructure

These stack diagrams are meant to show internal resource relationships, dependencies, and exported values within one Pulumi stack.

4. The master/prod-infrastructure-overview.md file is the top-level system view. It is the diagram that ties the stacks together and shows inter-stack dependencies, security boundaries, and data flow across the full production environment.

5. The underlying runtime architecture being documented is an AWS-based container platform in us-east-1:

- VPC, subnets, routing, and internet connectivity

- ECS cluster and ECS services

- Fargate-hosted containerized application

- IAM roles/policies

- CloudWatch logging with retention

So the diagrams represent a containerized web application on AWS, not a general-purpose app repo.

6. The primary data flow boundary is network traffic from external clients into the VPC and onward to the ECS service running the Nginx container. The diagrams are expected to show network paths with dotted Mermaid edges, while stack outputs/inputs and permissions are shown as dependency edges between stacks or resources.

7. The repo also encodes visual conventions as a first-class concern. VISUAL_STANDARDS.md defines the diagram language:

- Mermaid syntax

- AWS-inspired color categories for IAM, networking, compute, containers, logging, external systems, and outputs

- Standard node labels for resources, IDs, and config values

This makes the diagrams consistent enough to be used as architecture references.

8. templates/ provides the scaffolding for new diagrams:

- stack-template.md

- master-template.md

These templates define the expected structure for future stack diagrams and future environment-level overviews.

9. UPDATE_PROCEDURES.md defines the maintenance workflow. Diagrams are treated as living documentation and should be updated when resource sets, configurations, security posture, or cross-stack dependencies change. The process centers on comparing against Pulumi resource state, editing the relevant Markdown diagrams, and validating the result.

10. The repository includes automation hooks around diagram correctness. The README references validation and generation scripts plus CI/CD integration, implying a pipeline that checks Mermaid syntax and helps regenerate diagrams from Pulumi state. In architecture terms, this is a documentation quality-control layer rather than an application runtime layer.

11. The key system boundary represented here is the separation of concerns between infrastructure layers:

- IAM controls identity and permissions

- Network controls connectivity and isolation

- Cluster controls compute and application execution

The master diagram should show how these layers interact, while the stack diagrams should stay inside their own operational scope.

12. Overall, the repo’s architecture is: Pulumi production state as the source of truth, Markdown/Mermaid files as the visualization layer, templates and standards as governance, and validation/update procedures as the maintenance pipeline. An accurate diagram of this repository would therefore show documentation assets centered around three production stacks and one cross-stack overview.