sohaibmohd18/saas-backend-infra-on-aws

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.