# aliabbasjaffri/ecs-terraform-terragrunt architecture

> Architecture diagram of the GitHub repository aliabbasjaffri/ecs-terraform-terragrunt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aliabbasjaffri/ecs-terraform-terragrunt
- Repository: https://github.com/aliabbasjaffri/ecs-terraform-terragrunt

## Overview

##### What this project is (type + purpose)
This repo is **Infrastructure-as-Code** for deploying a **containerized Ghost “API” service** on **AWS ECS Fargate**, fronted by an **Application Load Balancer (ALB)**, inside a dedicated **VPC + subnets**, with the intent to support **autoscaling** (mentioned in README; may or may not be fully implemented in the Terraform modules).

- **Terraform** (`terraform/…`) defines reusable modules for AWS resources.
- **Terragrunt** (`terragrunt/…`) supplies environment-specific configuration, wiring, dependency ordering, and “run-all apply” orchestration.

##### Terraform modules (the “building blocks”)
Located under `terraform/`:
- `vpc_subnet_module/`: VPC, subnets, routing, internet gateway (per README).
- `ecs_cluster/`: ECS cluster (for Fargate).
- `aws_alb/`: Application Load Balancer (listeners/target groups likely here).
- `ecs_application/`: ECS service/task definition that runs the Ghost container and registers with ALB target group.

Each module has `main.tf`, `variables.tf`, `outputs.tf` → that implies explicit inputs/outputs and therefore explicit **module-to-module coupling** (e.g., ALB module outputs a target group ARN; ECS app consumes it).

##### Terragrunt live configuration (the “assembly + environment”)
Located under `terragrunt/`:
- `base-infrastructure/dev/...`: environment “dev” for foundational resources:
- `vpc_subnet_module`
- `ecs_cluster`
- `aws_alb`
- `applications/dev/ecs_application`: application layer deployed into the base infra.
- `stage.hcl`, `root-config.hcl`, `terragrunt.hcl`: shared settings, remote state, providers, common locals, etc.

This layout strongly suggests **two tiers**:

##### ECS Tasks → response back through ALB → client

Also add:

##### Control-plane (deployment and infra wiring)
- **Terragrunt** (as orchestrator) → **Terraform modules** (apply order / dependencies)
- **ecs_application module** depends on outputs from:
- `ecs_cluster` (cluster ARN/name)
- `aws_alb` (target group ARN, listener rules, security group IDs)
- `vpc_subnet_module` (subnet IDs, VPC ID)
- `service_role` (role ARNs)

##### Architectural patterns/design principles to highlight
- **Layering**: base-infrastructure vs application deployments (Terragrunt directories reflect this).
- **Module boundaries**: each AWS concern is isolated as a Terraform module with explicit variables/outputs.
- **Environment isolation**: `dev` is a full, dedicated environment; can be replicated to `staging`/`prod` via additional terragrunt folders.
- **Immutable-ish deployments**: ECS task definitions/services encourage replaceable tasks rather than in-place server mutation.

##### What technologies to label prominently
- **Terraform modules**: `vpc_subnet_module`, `aws_alb`, `ecs_cluster`, `ecs_application`, `service_role`
- **AWS services**: VPC, Subnets, IGW, ALB, ECS (Fargate), IAM

##### Diagramming conventions (what I expect you to include)

- “routes traffic to”
- “registers targets”
- “assumes role”
- “reads outputs”

##### Don’t overthink it: split into many components
Given the repo’s intent, “best” means you explicitly separate:
- VPC vs subnets vs routing/IGW
- ALB vs listener vs target group
- ECS cluster vs service vs task definition vs running tasks
- IAM service/task roles
- Terragrunt live config vs Terraform modules

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram A — Cloud Runtime Architecture (AWS)
%% =========================
subgraph A["Diagram A — Cloud Runtime Architecture (AWS)"]
  direction TB

  Client["Client / Internet User"]:::external

  subgraph VPC["VPC (terraform: vpc_subnet_module)"]
    direction TB

    subgraph Pub["Public Subnets"]
      direction TB
      ALB["Application Load Balancer (terraform: aws_alb)"]:::ingress
      Listener80["Listener :80 (HTTP)"]:::ingress
      TG["Target Group"]:::ingress
    end

    subgraph Priv["Private Subnets"]
      direction TB
      ECSCluster["ECS Cluster (Fargate) (terraform: ecs_cluster)"]:::compute
      ECSService["ECS Service (terraform: ecs_application)"]:::compute
      TaskDef["Task Definition (Ghost container image)"]:::compute
      Tasks["Running Tasks/Containers (Ghost)"]:::compute
    end

    subgraph Routing["Routing & Edge"]
      direction TB
      RT["Route Tables"]:::network
      IGW["Internet Gateway"]:::network
    end
  end

  subgraph IAM["Identity & Permissions (terraform: service_role)"]
    direction TB
    ExecRole["IAM Task Execution Role"]:::iam
    TaskRole["IAM Task Role"]:::iam
  end

  %% Data-plane flow
  Client -->|"HTTP request"| ALB
  ALB -->|"forwards to"| Listener80
  Listener80 -->|"routes traffic to"| TG
  TG -->|"targets"| Tasks
  Tasks -->|"HTTP response"| ALB
  ALB -->|"HTTP response"| Client

  %% Health checks
  ALB -.->|"health checks"| Tasks

  %% ECS internal relationships
  ECSCluster -->|"runs"| ECSService
  ECSService -->|"uses"| TaskDef
  TaskDef -->|"spawns"| Tasks

  %% IAM attachments
  ECSService -->|"assumes role"| ExecRole
  Tasks -->|"assumes role"| TaskRole

  %% Networking association hints (conceptual)
  ALB -->|"deployed in"| Pub
  ECSService -->|"deployed in"| Priv
  Pub -->|"routes via"| IGW
  RT -->|"associates"| Pub
  RT -->|"associates"| Priv
end

%% =========================
%% Diagram B — IaC / Module Dependency (Terragrunt + Terraform)
%% =========================
subgraph B["Diagram B — IaC / Module Dependency (Terragrunt + Terraform)"]
  direction TB

  subgraph TGroot["Terragrunt Global Configuration"]
    direction TB
    TGConfig["terragrunt/{terragrunt.hcl, root-config.hcl}"]:::iac
  end

  subgraph TGLive["Terragrunt Live Layout"]
    direction TB

    subgraph TGBase["Tier 1 — base-infrastructure/dev"]
      direction TB
      TGBaseDir["terragrunt/base-infrastructure/dev/"]:::iac
      TGBaseStage["stage.hcl (base infra)"]:::iac

      TGVPCcfg["vpc_subnet_module/terragrunt.hcl"]:::iac
      TGECSClustercfg["ecs_cluster/terragrunt.hcl"]:::iac
      TGALBcfg["aws_alb/terragrunt.hcl"]:::iac
    end

    subgraph TGApps["Tier 2 — applications/dev"]
      direction TB
      TGAppsDir["terragrunt/applications/dev/"]:::iac
      TGAppsStage["stage.hcl (apps)"]:::iac
      TGECSAppcfg["ecs_application/terragrunt.hcl"]:::iac
    end
  end

  subgraph TFMods["Terraform Modules (reusable building blocks)"]
    direction TB
    TFVPC["terraform/vpc_subnet_module"]:::tf
    TFECSCluster["terraform/ecs_cluster"]:::tf
    TFALB["terraform/aws_alb"]:::tf
    TFRole["terraform/service_role"]:::tf
    TFECSApp["terraform/ecs_application"]:::tf
  end

  %% Terragrunt -> Terraform module invocations
  TGConfig -->|"configures"| TGBaseDir
  TGConfig -->|"configures"| TGAppsDir

  TGBaseDir -->|"includes"| TGBaseStage
  TGAppsDir -->|"includes"| TGAppsStage

  TGVPCcfg -->|"calls module"| TFVPC
  TGECSClustercfg -->|"calls module"| TFECSCluster
  TGALBcfg -->|"calls module"| TFALB
  TGECSAppcfg -->|"calls module"| TFECSApp

  %% Dependencies (outputs -> inputs)
  TFVPC -->|"outputs VPC/Subnet IDs"| TFALB
  TFVPC -->|"outputs VPC/Subnet IDs"| TFECSApp
  TFVPC -->|"provides network context"| TFECSCluster

  TFECSCluster -->|"outputs cluster ARN/name"| TFECSApp
  TFALB -->|"outputs target group/listener IDs"| TFECSApp
  TFRole -->|"outputs role ARNs"| TFECSApp

  %% Apply ordering / orchestration (terragrunt run-all)
  TGVPCcfg -.->|"apply order"| TGECSClustercfg
  TGVPCcfg -.->|"apply order"| TGALBcfg
  TGECSClustercfg -.->|"apply order"| TGECSAppcfg
  TGALBcfg -.->|"apply order"| TGECSAppcfg
end

%% =========================
%% Click Events (component mapping)
%% =========================
click TFVPC "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/vpc_subnet_module/main.tf"
click TFVPC "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/vpc_subnet_module/variables.tf"
click TFVPC "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/vpc_subnet_module/outputs.tf"

click TFECSCluster "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/ecs_cluster/main.tf"
click TFECSCluster "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/ecs_cluster/variables.tf"
click TFECSCluster "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/ecs_cluster/outputs.tf"

click TFALB "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/aws_alb/main.tf"
click TFALB "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/aws_alb/variables.tf"
click TFALB "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/aws_alb/outputs.tf"

click TFECSApp "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/ecs_application/main.tf"
click TFECSApp "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/ecs_application/variables.tf"
click TFECSApp "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/ecs_application/outputs.tf"

click TFRole "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/service_role/main.tf"
click TFRole "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/service_role/variables.tf"
click TFRole "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terraform/service_role/outputs.tf"

click TGConfig "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/terragrunt.hcl"
click TGConfig "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/root-config.hcl"

click TGBaseDir "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/tree/main/terragrunt/base-infrastructure/dev/"
click TGVPCcfg "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/base-infrastructure/dev/vpc_subnet_module/terragrunt.hcl"
click TGECSClustercfg "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/base-infrastructure/dev/ecs_cluster/terragrunt.hcl"
click TGALBcfg "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/base-infrastructure/dev/aws_alb/terragrunt.hcl"
click TGBaseStage "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/base-infrastructure/dev/stage.hcl"

click TGAppsDir "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/tree/main/terragrunt/applications/dev/"
click TGECSAppcfg "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/applications/dev/ecs_application/terragrunt.hcl"
click TGAppsStage "https://github.com/aliabbasjaffri/ecs-terraform-terragrunt/blob/main/terragrunt/applications/dev/stage.hcl"

%% =========================
%% Styles
%% =========================
classDef external fill:#111827,stroke:#0b1220,color:#ffffff,stroke-width:1.5px
classDef network fill:#DBEAFE,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1.5px
classDef ingress fill:#FEF3C7,stroke:#B45309,color:#3A2200,stroke-width:1.5px
classDef compute fill:#DCFCE7,stroke:#15803D,color:#06250F,stroke-width:1.5px
classDef iam fill:#FCE7F3,stroke:#BE185D,color:#3B001A,stroke-width:1.5px
classDef iac fill:#EDE9FE,stroke:#6D28D9,color:#1F1147,stroke-width:1.5px
classDef tf fill:#FFEDD5,stroke:#C2410C,color:#3A1400,stroke-width:1.5px
```
