# sohaibmohd18/saas-backend-infra-on-aws architecture

> Architecture diagram of the GitHub repository sohaibmohd18/saas-backend-infra-on-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sohaibmohd18/saas-backend-infra-on-aws
- Repository: https://github.com/sohaibmohd18/saas-backend-infra-on-aws

## Overview

1. This repository is primarily an AWS infrastructure codebase, not a full application stack. Terraform is the main control plane, and the runtime workload is a small containerized sample API used to validate the platform.

2. The infrastructure is split into three layers of Terraform state:
   - a one-time backend bootstrap that creates the remote state S3 bucket and DynamoDB lock table,
   - environment stacks for `dev`, `staging`, and `prod`,
   - reusable modules under `terraform/modules` for each AWS subsystem.

3. Network architecture is centered on a custom VPC with three tiers of subnets: public, application, and database. The load balancer lives in public subnets, ECS tasks run in private app subnets, and RDS lives in private DB subnets. NAT gateways and optional VPC endpoints are part of the network design, with the number of NATs increasing in higher environments.

4. The request path is simple and explicit: Internet traffic enters an Application Load Balancer, which forwards to ECS Fargate services, which then connect to RDS PostgreSQL. This is the core data plane the architecture diagram should show.

5. Compute is ECS Fargate, managed as a container service rather than EC2 instances. The service supports auto-scaling based on CPU and memory target tracking. Development favors lower-cost settings such as FARGATE_SPOT, while production emphasizes resilience.

6. Persistence is handled by Amazon RDS PostgreSQL 15. The database is private, encrypted, backed up automatically, and configured for Multi-AZ in production. There are no public IPs on ECS or RDS, so all app-to-database traffic stays inside the VPC.

7. Secrets and identity are separated into dedicated modules. Secrets Manager stores database credentials and app secrets using environment-scoped paths, while IAM provides least-privilege roles, including the GitHub Actions OIDC role used for deployment without long-lived AWS keys.

8. The container registry is an AWS ECR repository provisioned by Terraform. The deployment workflow first seeds the repository with a placeholder image, then later GitHub Actions builds the app image and pushes it to ECR for ECS to pull.

9. CI/CD is handled through three GitHub Actions workflows:
   - Terraform plan on pull requests,
   - Terraform apply on pushes to main, with staging/prod protected by GitHub environment approvals,
   - app deployment that builds the container image and updates ECS.
   This makes the repo operate as both infrastructure source and deployment pipeline.

10. Monitoring is a first-class subsystem. A CloudWatch dashboard and alarms cover ECS, ALB, and RDS, and alarms notify via SNS email. This gives the architecture both service-health visibility and operational alerting.

11. Environment differences are important to the topology:
   - `dev` is cost-optimized and lighter weight,
   - `staging` adds more production-like networking and sizing,
   - `prod` is the most hardened, with Multi-AZ RDS, deletion protection, and stronger network redundancy.
   The diagram should show the same logical shape across all three, with production having the most redundancy.

12. The `app/sample-api` directory contains a small FastAPI service with `/`, `/health`, and `/info` endpoints. It exists to exercise the infrastructure path end-to-end; it is not the main product logic of the repository.

13. In terms of boundaries, the key separation is:
   - Terraform modules define AWS infrastructure primitives,
   - environment stacks compose those primitives into deployable environments,
   - GitHub Actions orchestrates provisioning and application deployment,
   - the sample app is the payload that runs on ECS.

14. A good architecture diagram for this repo should emphasize the following flows:
   - developer or CI → Terraform backend/state → AWS resources,
   - GitHub Actions → ECR → ECS service,
   - Internet → ALB → ECS tasks → RDS,
   - CloudWatch alarms → SNS → email.
   Those are the main operational and data-flow boundaries in the system.

Main entry points: [`terraform/environments/dev/main.tf`](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/dev/main.tf) (Dev stack), [`terraform/environments/staging/main.tf`](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/staging/main.tf) (Staging stack), [`terraform/environments/prod/main.tf`](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/prod/main.tf) (Prod stack), [`terraform/modules/ecs/main.tf`](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/ecs/main.tf) (ECS service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_terraform["Terraform"]
  node_backend_bootstrap["Backend bootstrap<br/>terraform bootstrap<br/>[main.tf]"]
  node_env_dev["Dev stack<br/>terraform env<br/>[main.tf]"]
  node_env_staging["Staging stack<br/>terraform env<br/>[main.tf]"]
  node_env_prod["Prod stack<br/>terraform env<br/>[main.tf]"]
end

subgraph group_cicd["GitHub Actions"]
  node_plan_wf["Plan workflow<br/>GitHub Actions<br/>[terraform-plan.yml]"]
  node_apply_wf["Apply workflow<br/>GitHub Actions"]
  node_deploy_wf["Deploy workflow<br/>GitHub Actions<br/>[app-deploy.yml]"]
end

subgraph group_runtime["AWS Runtime"]
  node_vpc["VPC<br/>network module<br/>[main.tf]"]
  node_security["Security groups<br/>network security<br/>[main.tf]"]
  node_alb["Load balancer<br/>ALB module<br/>[main.tf]"]
  node_ecs["ECS service<br/>Fargate service<br/>[main.tf]"]
  node_rds[("PostgreSQL<br/>RDS module<br/>[main.tf]")]
  node_ecr["Container registry<br/>ECR repo<br/>[main.tf]"]
  node_iam["IAM roles<br/>IAM module<br/>[main.tf]"]
  node_secrets["Secrets store<br/>Secrets module<br/>[main.tf]"]
  node_monitoring["Monitoring<br/>CloudWatch module<br/>[main.tf]"]
end

subgraph group_app["Sample App"]
  node_sample_api["Sample API<br/>FastAPI app<br/>[main.py]"]
end

node_backend_bootstrap -->|"remote state"| node_env_dev
node_backend_bootstrap -->|"remote state"| node_env_staging
node_backend_bootstrap -->|"remote state"| node_env_prod
node_env_dev -->|"composes"| node_vpc
node_env_dev -->|"composes"| node_security
node_env_dev -->|"composes"| node_alb
node_env_dev -->|"composes"| node_ecs
node_env_dev -->|"composes"| node_rds
node_env_dev -->|"composes"| node_ecr
node_env_dev -->|"composes"| node_iam
node_env_dev -->|"composes"| node_secrets
node_env_dev -->|"composes"| node_monitoring
node_env_staging -->|"composes"| node_vpc
node_env_staging -->|"composes"| node_security
node_env_staging -->|"composes"| node_alb
node_env_staging -->|"composes"| node_ecs
node_env_staging -->|"composes"| node_rds
node_env_staging -->|"composes"| node_ecr
node_env_staging -->|"composes"| node_iam
node_env_staging -->|"composes"| node_secrets
node_env_staging -->|"composes"| node_monitoring
node_env_prod -->|"composes"| node_vpc
node_env_prod -->|"composes"| node_security
node_env_prod -->|"composes"| node_alb
node_env_prod -->|"composes"| node_ecs
node_env_prod -->|"composes"| node_rds
node_env_prod -->|"composes"| node_ecr
node_env_prod -->|"composes"| node_iam
node_env_prod -->|"composes"| node_secrets
node_env_prod -->|"composes"| node_monitoring
node_alb -->|"forwards"| node_ecs
node_ecs -->|"queries"| node_rds
node_deploy_wf -->|"pushes image"| node_ecr
node_deploy_wf -->|"updates service"| node_ecs
node_plan_wf -->|"plans"| node_env_dev
node_apply_wf -->|"applies"| node_env_dev
node_apply_wf -->|"applies"| node_env_staging
node_apply_wf -->|"applies"| node_env_prod
node_apply_wf -->|"assumes role"| node_iam
node_deploy_wf -->|"assumes role"| node_iam
node_deploy_wf -->|"builds"| node_sample_api
node_sample_api -->|"runs on"| node_ecs
node_monitoring -->|"watches"| node_ecs
node_monitoring -->|"watches"| node_alb
node_monitoring -->|"watches"| node_rds
node_monitoring -->|"alerts via"| node_secrets

click node_backend_bootstrap "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/backend/bootstrap/main.tf"
click node_env_dev "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/dev/main.tf"
click node_env_staging "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/staging/main.tf"
click node_env_prod "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/prod/main.tf"
click node_vpc "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/vpc/main.tf"
click node_security "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/security/main.tf"
click node_alb "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/alb/main.tf"
click node_ecs "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/ecs/main.tf"
click node_rds "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/rds/main.tf"
click node_ecr "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/ecr/main.tf"
click node_iam "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/iam/main.tf"
click node_secrets "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/secrets/main.tf"
click node_monitoring "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/monitoring/main.tf"
click node_plan_wf "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/.github/workflows/terraform-plan.yml"
click node_apply_wf "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/.github/workflows/terraform-apply.yml"
click node_deploy_wf "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/.github/workflows/app-deploy.yml"
click node_sample_api "https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/app/sample-api/main.py"

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_backend_bootstrap,node_env_dev,node_env_staging,node_env_prod toneBlue
class node_plan_wf,node_apply_wf,node_deploy_wf toneAmber
class node_vpc,node_security,node_alb,node_ecs,node_rds,node_ecr,node_iam,node_secrets,node_monitoring toneMint
class node_sample_api toneRose
```

## Components

### Terraform

Infrastructure control plane, state bootstrap, and environment composition

- [Backend bootstrap](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/backend/bootstrap/main.tf): terraform bootstrap · Creates the remote state bucket and lock table for Terraform · `terraform/backend/bootstrap/main.tf`
- [Dev stack](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/dev/main.tf): terraform env · Cost-optimized environment composition · `terraform/environments/dev/main.tf`
- [Staging stack](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/staging/main.tf): terraform env · Production-like preproduction environment · `terraform/environments/staging/main.tf`
- [Prod stack](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/environments/prod/main.tf): terraform env · Hardened production environment with highest redundancy · `terraform/environments/prod/main.tf`

### GitHub Actions

Provisioning and application delivery workflows

- [Plan workflow](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/.github/workflows/terraform-plan.yml): GitHub Actions · Runs Terraform plan on pull requests · `.github/workflows/terraform-plan.yml`
- [Apply workflow](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/.github/workflows/terraform-apply.yml): GitHub Actions · Runs Terraform apply on main with environment approvals · `.github/workflows/terraform-apply.yml`
- [Deploy workflow](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/.github/workflows/app-deploy.yml): GitHub Actions · Builds the app image, pushes to ECR, and updates ECS · `.github/workflows/app-deploy.yml`

### AWS Runtime

Deployed AWS services and data plane

- [VPC](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/vpc/main.tf): network module · Custom VPC with public, app, and database subnet tiers · `terraform/modules/vpc/main.tf`
- [Security groups](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/security/main.tf): network security · Traffic boundaries for ALB, ECS, and RDS · `terraform/modules/security/main.tf`
- [Load balancer](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/alb/main.tf): ALB module · Internet-facing entry point in public subnets · `terraform/modules/alb/main.tf`
- [ECS service](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/ecs/main.tf): Fargate service · Container service running private app tasks with auto-scaling · `terraform/modules/ecs/main.tf`
- [PostgreSQL](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/rds/main.tf): RDS module · Private PostgreSQL 15 database with backups and Multi-AZ in prod · `terraform/modules/rds/main.tf`
- [Container registry](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/ecr/main.tf): ECR repo · Registry seeded by Terraform and later populated by CI builds · `terraform/modules/ecr/main.tf`
- [IAM roles](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/iam/main.tf): IAM module · Least-privilege roles including GitHub Actions OIDC access · `terraform/modules/iam/main.tf`
- [Secrets store](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/secrets/main.tf): Secrets module · Environment-scoped application and database secrets · `terraform/modules/secrets/main.tf`
- [Monitoring](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/terraform/modules/monitoring/main.tf): CloudWatch module · Dashboards, alarms, and SNS notifications for ECS, ALB, and RDS · `terraform/modules/monitoring/main.tf`

### Sample App

Containerized FastAPI payload used to exercise the platform

- [Sample API](https://github.com/sohaibmohd18/saas-backend-infra-on-aws/blob/main/app/sample-api/main.py): FastAPI app · Minimal containerized payload with health and info endpoints · `app/sample-api/main.py`

## Connections

- Backend bootstrap → Dev stack: remote state · Environment stack uses the bootstrap-created backend
- Backend bootstrap → Staging stack: remote state · Environment stack uses the bootstrap-created backend
- Backend bootstrap → Prod stack: remote state · Environment stack uses the bootstrap-created backend
- Dev stack → VPC: composes · Dev stack instantiates the shared network foundation
- Dev stack → Security groups: composes · Dev stack wires security boundaries
- Dev stack → Load balancer: composes · Dev stack provisions the entry load balancer
- Dev stack → ECS service: composes · Dev stack provisions the container service
- Dev stack → PostgreSQL: composes · Dev stack provisions the database tier
- Dev stack → Container registry: composes · Dev stack provisions the image repository
- Dev stack → IAM roles: composes · Dev stack provisions roles and policies
- Dev stack → Secrets store: composes · Dev stack provisions secrets access and storage
- Dev stack → Monitoring: composes · Dev stack provisions observability resources
- Staging stack → VPC: composes · Staging stack instantiates the shared network foundation
- Staging stack → Security groups: composes · Staging stack wires security boundaries
- Staging stack → Load balancer: composes · Staging stack provisions the entry load balancer
- Staging stack → ECS service: composes · Staging stack provisions the container service
- Staging stack → PostgreSQL: composes · Staging stack provisions the database tier
- Staging stack → Container registry: composes · Staging stack provisions the image repository
- Staging stack → IAM roles: composes · Staging stack provisions roles and policies
- Staging stack → Secrets store: composes · Staging stack provisions secrets access and storage
- Staging stack → Monitoring: composes · Staging stack provisions observability resources
- Prod stack → VPC: composes · Prod stack instantiates the shared network foundation
- Prod stack → Security groups: composes · Prod stack wires security boundaries
- Prod stack → Load balancer: composes · Prod stack provisions the entry load balancer
- Prod stack → ECS service: composes · Prod stack provisions the container service
- Prod stack → PostgreSQL: composes · Prod stack provisions the database tier
- Prod stack → Container registry: composes · Prod stack provisions the image repository
- Prod stack → IAM roles: composes · Prod stack provisions roles and policies
- Prod stack → Secrets store: composes · Prod stack provisions secrets access and storage
- Prod stack → Monitoring: composes · Prod stack provisions observability resources
- Load balancer → ECS service: forwards · ALB routes inbound requests to ECS services
- ECS service → PostgreSQL: queries · Tasks connect privately to PostgreSQL
- Deploy workflow → Container registry: pushes image · Workflow builds and publishes the application container image
- Deploy workflow → ECS service: updates service · Workflow deploys the new task definition or service revision
- Plan workflow → Dev stack: plans · Pull request workflow validates Terraform changes
- Apply workflow → Dev stack: applies · Main branch apply provisions or updates the dev environment
- Apply workflow → Staging stack: applies · Main branch apply provisions or updates the staging environment
- Apply workflow → Prod stack: applies · Main branch apply provisions or updates the prod environment
- Apply workflow → IAM roles: assumes role · GitHub Actions uses OIDC-based deployment access
- Deploy workflow → IAM roles: assumes role · Deployment workflow uses OIDC-based AWS access
- Deploy workflow → Sample API: builds · Workflow packages the FastAPI service into a container image
- Sample API → ECS service: runs on · Sample API is the payload executed by ECS tasks
- Monitoring → ECS service: watches · CloudWatch alarms track service health and scaling
- Monitoring → Load balancer: watches · CloudWatch alarms track load balancer health and traffic
- Monitoring → PostgreSQL: watches · CloudWatch alarms track database availability and performance
- Monitoring → Secrets store: alerts via · Alarms notify through SNS email subscriptions