# Architecture diagrams runbook

Purpose of the `docs/architecture-diagrams` folder and how to use it.

## Purpose

The **architecture-diagrams** folder holds tooling and specifications for generating **AWS-style architecture diagrams** for this project. The diagrams depict the full stack: Wiki.js on Amazon EKS (Auto Mode), Terraform layers (bootstrap through app), DNS and TLS (domain vs deployment account), VPC, RDS, S3, Argo CD, and CI (GitHub Actions with OIDC).

Generated diagrams are intended to look like professional AWS Solution Architect outputs: clear boundaries, AWS-style components and icons, labeled data and control flows, and consistent tier grouping. They are driven by:

- **INSTRUCTIONS.md** - Scenario, account model, prerequisites, and component list that the diagram must reflect (e.g. 00-bootstrap, 10-network, 20-eks, 30-data-rds, 35-storage-s3-assets, 40-platform, 45-argocd, 50-app-wikijs).
- **AGENT.md** - Guidance for agents (or automation) that collect Terraform plan JSON and produce diagrams.
- **SETUP.md** - Environment setup for the diagram tooling (Python, Graphviz, AWS CLI, jq, Terraform, credentials).

Use this folder when you need to create or update the project's architecture diagram or run the diagram generation pipeline.

## Setup

To prepare your environment for generating or updating architecture diagrams (install Python, Graphviz, and configure AWS/Terraform access), follow the setup guide:

**[Architecture diagrams setup →](../architecture-diagrams/SETUP.md)**

That guide covers prerequisites, verification steps, and setup on macOS and Ubuntu.

## Prompt for AI assistants (Copilot, Cursor, etc.)

Use this prompt in your IDE (Copilot, Cursor, or similar) or in a terminal-based AI tool to set up the environment and generate the architectural diagrams in one go:

```prompt
CONTEXT DIRECTORY: terraform
TASKS:
- Set up the environment as per @docs/architecture-diagrams/SETUP.md.
- Use @docs/architecture-diagrams/AGENT.md for your system instructions.
- Once done, read the @docs/architecture-diagrams/INSTRUCTIONS.md and create the architectural diagrams.
```