From 28f3b5a9ec842c39145a080a37d42459a9c33acb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dafydd=20Ll=C5=B7r=20Pearson?= <DafyddLlyr@gmail.com>
Date: Wed, 20 Nov 2024 20:56:30 +0000
Subject: [PATCH] docs: Add mermaid diagrams explaining .env files [skip pizza]

---
 doc/how-to/how-to-add-a-secret.md | 51 ++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/doc/how-to/how-to-add-a-secret.md b/doc/how-to/how-to-add-a-secret.md
index 72332e6f66..5e6a8a07e0 100644
--- a/doc/how-to/how-to-add-a-secret.md
+++ b/doc/how-to/how-to-add-a-secret.md
@@ -14,6 +14,7 @@ This guide will demonstrate how to -
 2. Add to your local `.env` file for local development
    - Note: This file is never checked into our public repository and is listed in our `.gitignore` config
 3. Document the secret in `.env.example`
+4. If a secret is required for a unit test, add dummy values to corresponding `.env.test` files e.g `YOUR_NEW_SECRET=test`
 
 ### Docker Environments (Local development + Pizza environments)
 To pass a secret into our Docker Compose setup you will need to map it into the relevant container in `docker-compose.yml`. For example - 
@@ -35,6 +36,39 @@ When building Pizza environments for testing, GitHub actions access secrets via
 > Please be aware that if you are rotating secrets this may affect existing Pizzas which will need to be rebuilt. This can be done manually in GitHub by re-running the latest action associated with affected PRs.
 
 
+## Diagram - Docker environments
+```mermaid
+flowchart LR
+    subgraph "Local Environment"
+        localEnv[".env file(s)"] --> Docker["Docker Compose"]
+        Docker --> API
+        Docker --> Hasura
+        Docker --> Frontend
+    end
+
+    subgraph Staging AWS S3 bucket
+        S3
+    end
+
+    subgraph GitHub actions
+        pizzaEnv[".env file"]
+    end
+
+    subgraph "Pizza Environment"
+        pizzaEnv[".env file"] --> PizzaDocker["Docker Compose"]
+        PizzaDocker --> PizzaAPI["API"]
+        PizzaDocker --> PizzaHasura["Hasura"]
+        PizzaDocker --> PizzaFrontend["Frontend"]
+    end
+
+    %% Scripts reading and writing
+    S3 --"Pull/Push scripts"--> localEnv
+
+    %% CI
+    S3 --> pizzaEnv
+```
+
+
 ### AWS / Pulumi Environments (Staging + Production environments)
 Secrets for Staging and Production environment are not handled in `.env` files, and are set directly in Pulumi, our Infrastruture as Code (IaC) platform.
 
@@ -68,4 +102,19 @@ const apiService = new awsx.ecs.FargateService("api", {
 });
 ```
 
-> Pulumi uses our Docker images to construct Fargate services. This means that the "name" value above must match that used in Docker.
\ No newline at end of file
+> Pulumi uses our Docker images to construct Fargate services. This means that the "name" value above must match that used in Docker.
+
+## Diagram - AWS / Pulumi Environments
+```mermaid
+flowchart LR
+    subgraph "Staging & Production"
+        direction LR
+
+        PulumiService["Pulumi Service"] --"Private key"--> Pulumi
+        PulumiFile["pulumi.staging.yaml"] --"Public key"--> Pulumi
+        Pulumi["Pulumi IaC code"] --Decrypted--> Fargate
+        Fargate --> FargateAPI["API"]
+        Fargate --> FargateHasura["Hasura"]
+        Fargate --> FargateFrontend["Frontend"]
+    end
+```
\ No newline at end of file