# euron-tech/bluegreen_test architecture

> Architecture diagram of the GitHub repository euron-tech/bluegreen_test, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/euron-tech/bluegreen_test
- Repository: https://github.com/euron-tech/bluegreen_test

## Overview

#### Purpose and entry points
This is a teaching-scale FastAPI service demonstrating zero-downtime AWS ECS/Fargate blue-green deployment with automatic rollback. Runtime entry point is `app/main.py`; containerization starts at `Dockerfile`; local multi-service execution is `docker-compose.yml`. Deployment orchestration is available through `deploy.ps1` and GitHub Actions at `.github/workflows/deploy.yml`.

#### Application and HTTP contract
The FastAPI app serves the color-coded page, health endpoint, and metrics endpoint used by ALB, smoke tests, and monitoring. `app/observability.py` adds structured logging, request IDs, and metrics instrumentation around application requests. Presentation assets are isolated in `app/templates/index.html` and `app/static/style.css`.

#### Container and local environments
The image packages the Python 3.12/FastAPI application for Linux AMD64 Fargate execution (`Dockerfile`, `requirements.txt`). `docker-compose.yml` supports local blue on port 8000, optional green on 9000, and opt-in observability/load profiles. This mirrors the production separation between public production traffic and deployment validation traffic.

#### AWS traffic and compute plane
Terraform provisions the network, public ALB, port 80 production listener, port 9000 test listener, two swappable target groups, ECR, ECS cluster/service, Fargate task definition, IAM roles, and GitHub OIDC trust. The central infrastructure definition is `terraform/main.tf`, with environment and trust inputs in `terraform/variables.tf` and externally consumed endpoints/role ARNs in `terraform/outputs.tf`.

#### Blue-green deployment control plane
CodeDeploy coordinates ECS blue-green releases: a candidate task set is validated through the green listener before traffic is shifted on the production listener; failed health checks retain or restore the live version. `appspec.yaml` declares the CodeDeploy deployment binding. `.github/workflows/deploy.yml` runs branch-specific flow: `dev` validates/builds only, while `test` deploys and checks port 9000, and `main` promotes through production blue-green deployment.

#### Delivery and verification flow
The bootstrap path resolves the ECR/image-before-ECS dependency: create ECR, build/push image, then provision remaining infrastructure. `deploy.ps1` automates preflight, tests, image publishing, Terraform, GitHub role setup, deployment watching, and smoke validation. Post-deployment availability is checked by `scripts/smoke-test.sh`; `/health` is the critical boundary between application correctness and ALB/CodeDeploy promotion.

#### Observability and operations
Production observability uses CloudWatch Logs, metrics/alarm resources, SNS notification, log metric filters, and a CloudWatch dashboard defined in `terraform/monitoring.tf`. The local observability stack uses Prometheus, Grafana, Loki, Promtail, and Alertmanager, configured under `monitoring/prometheus.yml`, `monitoring/loki-config.yml`, and `monitoring/grafana/`. GitHub authenticates to AWS through short-lived OIDC credentials rather than stored AWS keys.

Main entry points: [`terraform/main.tf`](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf) (Terraform platform), [`app/main.py`](https://github.com/euron-tech/bluegreen_test/blob/main/app/main.py) (FastAPI service), [`Dockerfile`](https://github.com/euron-tech/bluegreen_test/blob/main/Dockerfile) (Fargate image), [`deploy.ps1`](https://github.com/euron-tech/bluegreen_test/blob/main/deploy.ps1) (Deployment bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_fastapi["FastAPI service<br/>Python API<br/>[main.py]"]
  node_instrumentation["Request instrumentation<br/>observability middleware<br/>[observability.py]"]
  node_ui_assets["Page assets<br/>template and CSS<br/>[index.html]"]
end

subgraph group_container["Container &amp; Local"]
  node_image["Fargate image<br/>Docker image"]
  node_local_stack["Local blue/green stack<br/>Docker Compose<br/>[docker-compose.yml]"]
end

subgraph group_aws["AWS Platform"]
  node_ecr[("ECR repository<br/>container registry<br/>[main.tf]")]
  node_alb["Public ALB<br/>traffic entry point<br/>[main.tf]"]
  node_target_groups["Blue / green target groups<br/>swappable backends<br/>[main.tf]"]
  node_ecs["ECS Fargate service<br/>compute service<br/>[main.tf]"]
  node_infra["Terraform platform<br/>infrastructure definition<br/>[main.tf]"]
end

subgraph group_delivery["Delivery Control"]
  node_codedeploy["CodeDeploy<br/>blue-green controller<br/>[appspec.yaml]"]
  node_github_actions["GitHub deployment workflow<br/>CI/CD workflow<br/>[deploy.yml]"]
  node_oidc["GitHub OIDC trust<br/>short-lived AWS auth<br/>[variables.tf]"]
  node_deploy_script["Deployment bootstrap<br/>PowerShell automation<br/>[deploy.ps1]"]
  node_smoke_test["Smoke validation<br/>deployment check<br/>[smoke-test.sh]"]
end

subgraph group_observability["Observability"]
  node_cloudwatch["CloudWatch monitoring<br/>logs, metrics, alarms<br/>[monitoring.tf]"]
  node_local_monitoring["Local monitoring stack<br/>[prometheus.yml]"]
end

node_instrumentation -->|"wraps requests"| node_fastapi
node_ui_assets -->|"rendered by"| node_fastapi
node_image -->|"packages"| node_fastapi
node_local_stack -->|"runs blue and green"| node_image
node_local_stack -.->|"enables profiles"| node_local_monitoring
node_infra -->|"provisions"| node_ecr
node_infra -->|"provisions"| node_alb
node_infra -->|"provisions"| node_target_groups
node_infra -->|"provisions"| node_ecs
node_image -->|"pushed to"| node_ecr
node_ecr -->|"image source"| node_ecs
node_alb -->|"routes production and test listeners"| node_target_groups
node_target_groups -->|"route to task sets"| node_ecs
node_github_actions -->|"authenticates through"| node_oidc
node_oidc -->|"assumes AWS role"| node_infra
node_github_actions -->|"starts promotion"| node_codedeploy
node_codedeploy -->|"validates and shifts traffic"| node_target_groups
node_deploy_script -->|"builds and publishes"| node_image
node_deploy_script -->|"applies"| node_infra
node_deploy_script -->|"runs"| node_smoke_test
node_smoke_test -->|"checks /health"| node_alb
node_fastapi -->|"emits production telemetry"| node_cloudwatch
node_fastapi -.->|"exposes local metrics and logs"| node_local_monitoring

click node_fastapi "https://github.com/euron-tech/bluegreen_test/blob/main/app/main.py"
click node_instrumentation "https://github.com/euron-tech/bluegreen_test/blob/main/app/observability.py"
click node_ui_assets "https://github.com/euron-tech/bluegreen_test/blob/main/app/templates/index.html"
click node_image "https://github.com/euron-tech/bluegreen_test/blob/main/Dockerfile"
click node_local_stack "https://github.com/euron-tech/bluegreen_test/blob/main/docker-compose.yml"
click node_ecr "https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf"
click node_alb "https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf"
click node_target_groups "https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf"
click node_ecs "https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf"
click node_infra "https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf"
click node_codedeploy "https://github.com/euron-tech/bluegreen_test/blob/main/appspec.yaml"
click node_github_actions "https://github.com/euron-tech/bluegreen_test/blob/main/.github/workflows/deploy.yml"
click node_oidc "https://github.com/euron-tech/bluegreen_test/blob/main/terraform/variables.tf"
click node_deploy_script "https://github.com/euron-tech/bluegreen_test/blob/main/deploy.ps1"
click node_smoke_test "https://github.com/euron-tech/bluegreen_test/blob/main/scripts/smoke-test.sh"
click node_cloudwatch "https://github.com/euron-tech/bluegreen_test/blob/main/terraform/monitoring.tf"
click node_local_monitoring "https://github.com/euron-tech/bluegreen_test/blob/main/monitoring/prometheus.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fastapi,node_instrumentation,node_ui_assets toneBlue
class node_image,node_local_stack toneAmber
class node_ecr,node_alb,node_target_groups,node_ecs,node_infra toneMint
class node_codedeploy,node_github_actions,node_oidc,node_deploy_script,node_smoke_test toneRose
class node_cloudwatch,node_local_monitoring toneIndigo
```

## Components

### Application

- [FastAPI service](https://github.com/euron-tech/bluegreen_test/blob/main/app/main.py): Python API · Serves page, health, and metrics endpoints. · `app/main.py`
- [Request instrumentation](https://github.com/euron-tech/bluegreen_test/blob/main/app/observability.py): observability middleware · Adds structured logs, request IDs, and metrics. · `app/observability.py`
- [Page assets](https://github.com/euron-tech/bluegreen_test/blob/main/app/templates/index.html): template and CSS · `app/templates/index.html`

### Container & Local

- [Fargate image](https://github.com/euron-tech/bluegreen_test/blob/main/Dockerfile): Docker image · Linux AMD64 FastAPI image. · `Dockerfile`
- [Local blue/green stack](https://github.com/euron-tech/bluegreen_test/blob/main/docker-compose.yml): Docker Compose · Runs blue, optional green, and opt-in monitoring profiles. · `docker-compose.yml`

### AWS Platform

- [ECR repository](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf): container registry · `terraform/main.tf`
- [Public ALB](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf): traffic entry point · Port 80 carries production traffic; port 9000 validates candidates. · `terraform/main.tf`
- [Blue / green target groups](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf): swappable backends · `terraform/main.tf`
- [ECS Fargate service](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf): compute service · Runs the active and candidate task sets. · `terraform/main.tf`
- [Terraform platform](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/main.tf): infrastructure definition · Provisions network, ALB, ECR, ECS, IAM, and deployment resources. · `terraform/main.tf`

### Delivery Control

- [CodeDeploy](https://github.com/euron-tech/bluegreen_test/blob/main/appspec.yaml): blue-green controller · Validates green before shifting production traffic and rolls back failures. · `appspec.yaml`
- [GitHub deployment workflow](https://github.com/euron-tech/bluegreen_test/blob/main/.github/workflows/deploy.yml): CI/CD workflow · Dev builds only; test validates port 9000; main promotes production. · `.github/workflows/deploy.yml`
- [GitHub OIDC trust](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/variables.tf): short-lived AWS auth · `terraform/variables.tf`
- [Deployment bootstrap](https://github.com/euron-tech/bluegreen_test/blob/main/deploy.ps1): PowerShell automation · Builds and publishes images, applies Terraform, watches deployment, and validates. · `deploy.ps1`
- [Smoke validation](https://github.com/euron-tech/bluegreen_test/blob/main/scripts/smoke-test.sh): deployment check · Uses /health as the promotion boundary. · `scripts/smoke-test.sh`

### Observability

- [CloudWatch monitoring](https://github.com/euron-tech/bluegreen_test/blob/main/terraform/monitoring.tf): logs, metrics, alarms · Publishes alarms, dashboards, log filters, and SNS notifications. · `terraform/monitoring.tf`
- [Local monitoring stack](https://github.com/euron-tech/bluegreen_test/blob/main/monitoring/prometheus.yml): Prometheus / Grafana / Loki · Provides local metrics, logs, dashboards, and alerting. · `monitoring/prometheus.yml`

## Connections

- Request instrumentation → FastAPI service: wraps requests
- Page assets → FastAPI service: rendered by
- Fargate image → FastAPI service: packages
- Local blue/green stack → Fargate image: runs blue and green
- Local blue/green stack → Local monitoring stack: enables profiles
- Terraform platform → ECR repository: provisions
- Terraform platform → Public ALB: provisions
- Terraform platform → Blue / green target groups: provisions
- Terraform platform → ECS Fargate service: provisions
- Fargate image → ECR repository: pushed to
- ECR repository → ECS Fargate service: image source
- Public ALB → Blue / green target groups: routes production and test listeners
- Blue / green target groups → ECS Fargate service: route to task sets
- GitHub deployment workflow → GitHub OIDC trust: authenticates through
- GitHub OIDC trust → Terraform platform: assumes AWS role
- GitHub deployment workflow → CodeDeploy: starts promotion
- CodeDeploy → Blue / green target groups: validates and shifts traffic
- Deployment bootstrap → Fargate image: builds and publishes
- Deployment bootstrap → Terraform platform: applies
- Deployment bootstrap → Smoke validation: runs
- Smoke validation → Public ALB: checks /health
- FastAPI service → CloudWatch monitoring: emits production telemetry
- FastAPI service → Local monitoring stack: exposes local metrics and logs