# adityacodes-root/devops-project architecture

> Architecture diagram of the GitHub repository adityacodes-root/devops-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adityacodes-root/devops-project
- Repository: https://github.com/adityacodes-root/devops-project

## Overview

1. This repo is a two-tier containerized web application with a clear split between a Next.js frontend and a FastAPI backend. The application is deployed as separate services rather than a monolith.

2. The backend lives in `backend/app/main.py` and is a Python/FastAPI service served with Uvicorn. Its unit tests are in `backend/app/test_main.py`, and dependencies are pinned in `backend/requirements.txt`.

3. The frontend lives in `frontend/pages/index.js` and is a Next.js app with server-side rendering. Frontend tests use Jest, with snapshots and setup files under `frontend/__tests__`, `frontend/jest.config.js`, and `frontend/jest.setup.js`.

4. At runtime, the browser talks to the frontend service first. The frontend is the user-facing entry point and is responsible for rendering the page and reaching the backend for application data or API responses.

5. Both tiers are containerized with multi-stage Docker builds (`backend/Dockerfile`, `frontend/Dockerfile`). That makes the deployable unit for each service a container image, which is what the cloud platforms run.

6. The repository supports two parallel production deployments:
   - AWS: container workloads run on ECS/Fargate behind an Application Load Balancer.
   - GCP: container workloads run on Cloud Run with managed HTTPS and autoscaling.
   In both cases, the services are provisioned as separate cloud resources for frontend and backend.

7. Terraform is the infrastructure boundary. `terraform/aws` defines the AWS environment: VPC, security groups, IAM, ECS, ALB, secrets, and CloudWatch monitoring. `terraform/gcp` defines the GCP environment: Cloud Run, Secret Manager, Cloud Monitoring, and remote state backend configuration.

8. Secrets are not hardcoded in the app. They are injected from AWS Secrets Manager or GCP Secret Manager, depending on the target cloud, which keeps runtime configuration outside the container images.

9. Monitoring is part of the infrastructure layer, not the app layer. AWS uses CloudWatch dashboards/alerts, while GCP uses Cloud Monitoring for service health, latency, and error tracking.

10. GitHub Actions provides the delivery pipeline. `.github/workflows/ci.yml` runs on `develop` for test/build validation, and `.github/workflows/cd.yml` runs on `main` to build/push images and apply Terraform for deployment.

11. The Terraform state is managed remotely for team use and recovery: S3 on AWS and Google Cloud Storage on GCP, rather than local state files.

12. The main architectural boundaries to show in a diagram are: user/browser, frontend container service, backend API service, cloud runtime/orchestration layer, secrets/monitoring services, and the CI/CD + Terraform control plane that builds and deploys everything.

Main entry points: [`terraform/aws/main.tf`](https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/main.tf) (AWS stack), [`terraform/gcp/main.tf`](https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/main.tf) (GCP stack), [`frontend/pages/index.js`](https://github.com/adityacodes-root/devops-project/blob/main/frontend/pages/index.js) (Frontend), [`backend/app/main.py`](https://github.com/adityacodes-root/devops-project/blob/main/backend/app/main.py) (Backend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_browser(("Browser<br/>client"))
  node_frontend_service["Frontend<br/>Next.js SSR<br/>[index.js]"]
  node_frontend_docker["Frontend image<br/>container build"]
  node_backend_service["Backend API<br/>FastAPI<br/>[main.py]"]
  node_backend_docker["Backend image<br/>container build"]
end

subgraph group_infra["Infrastructure"]
  node_aws_stack{{"AWS stack<br/>Terraform env<br/>[main.tf]"}}
  node_aws_vpc[("Networking<br/>AWS VPC<br/>[vpc.tf]")]
  node_aws_ecs["ECS/Fargate<br/>AWS runtime<br/>[ecs.tf]"]
  node_aws_alb["Load balancer<br/>AWS ALB<br/>[alb.tf]"]
  node_aws_secrets[("Secrets<br/>[secrets.tf]")]
  node_aws_monitoring["Monitoring<br/>CloudWatch<br/>[monitoring.tf]"]
  node_gcp_stack{{"GCP stack<br/>Terraform env<br/>[main.tf]"}}
  node_gcp_cloudrun["Cloud Run<br/>GCP runtime<br/>[cloudrun.tf]"]
  node_gcp_secrets[("Secrets<br/>Secret Manager<br/>[secrets.tf]")]
  node_gcp_monitoring["Monitoring<br/>[monitoring.tf]"]
end

subgraph group_delivery["Delivery"]
  node_ci["CI<br/>GitHub Actions<br/>[ci.yml]"]
  node_cd["CD<br/>GitHub Actions<br/>[cd.yml]"]
  node_terraform_state[("Remote state<br/>state backend<br/>[backend.tf]")]
end

node_browser -->|"uses"| node_frontend_service
node_frontend_service -->|"calls"| node_backend_service
node_frontend_service -->|"packaged as"| node_frontend_docker
node_backend_service -->|"packaged as"| node_backend_docker
node_aws_stack -->|"defines"| node_aws_vpc
node_aws_stack -->|"defines"| node_aws_ecs
node_aws_stack -->|"defines"| node_aws_alb
node_aws_stack -->|"defines"| node_aws_secrets
node_aws_stack -->|"defines"| node_aws_monitoring
node_aws_alb -->|"routes to"| node_frontend_service
node_aws_ecs -->|"runs"| node_frontend_docker
node_aws_ecs -->|"runs"| node_backend_docker
node_aws_secrets -.->|"injects"| node_backend_service
node_aws_monitoring -->|"watches"| node_aws_ecs
node_gcp_stack -->|"defines"| node_gcp_cloudrun
node_gcp_stack -->|"defines"| node_gcp_secrets
node_gcp_stack -->|"defines"| node_gcp_monitoring
node_gcp_cloudrun -->|"runs"| node_frontend_docker
node_gcp_cloudrun -->|"runs"| node_backend_docker
node_gcp_secrets -.->|"injects"| node_backend_service
node_gcp_monitoring -->|"watches"| node_gcp_cloudrun
node_ci -->|"tests"| node_frontend_service
node_ci -->|"tests"| node_backend_service
node_ci -->|"builds"| node_frontend_docker
node_ci -->|"builds"| node_backend_docker
node_cd -->|"builds/pushes"| node_frontend_docker
node_cd -->|"builds/pushes"| node_backend_docker
node_cd -->|"applies"| node_aws_stack
node_cd -->|"applies"| node_gcp_stack
node_terraform_state -.->|"stores state"| node_aws_stack
node_terraform_state -.->|"stores state"| node_gcp_stack

click node_frontend_service "https://github.com/adityacodes-root/devops-project/blob/main/frontend/pages/index.js"
click node_frontend_docker "https://github.com/adityacodes-root/devops-project/tree/main/frontend/Dockerfile"
click node_backend_service "https://github.com/adityacodes-root/devops-project/blob/main/backend/app/main.py"
click node_backend_docker "https://github.com/adityacodes-root/devops-project/tree/main/backend/Dockerfile"
click node_aws_stack "https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/main.tf"
click node_aws_vpc "https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/vpc.tf"
click node_aws_ecs "https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/ecs.tf"
click node_aws_alb "https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/alb.tf"
click node_aws_secrets "https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/secrets.tf"
click node_aws_monitoring "https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/monitoring.tf"
click node_gcp_stack "https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/main.tf"
click node_gcp_cloudrun "https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/cloudrun.tf"
click node_gcp_secrets "https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/secrets.tf"
click node_gcp_monitoring "https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/monitoring.tf"
click node_ci "https://github.com/adityacodes-root/devops-project/blob/main/.github/workflows/ci.yml"
click node_cd "https://github.com/adityacodes-root/devops-project/blob/main/.github/workflows/cd.yml"
click node_terraform_state "https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/backend.tf"

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_browser,node_frontend_service,node_frontend_docker,node_backend_service,node_backend_docker toneBlue
class node_aws_stack,node_aws_vpc,node_aws_ecs,node_aws_alb,node_aws_secrets,node_aws_monitoring,node_gcp_stack,node_gcp_cloudrun,node_gcp_secrets,node_gcp_monitoring toneAmber
class node_ci,node_cd,node_terraform_state toneMint
```

## Components

### Application

User-facing frontend and backend services

- **Browser**: client · End-user entry point
- [Frontend](https://github.com/adityacodes-root/devops-project/blob/main/frontend/pages/index.js): Next.js SSR · User-facing web app · `frontend/pages/index.js`
- [Frontend image](https://github.com/adityacodes-root/devops-project/tree/main/frontend/Dockerfile): container build · Multi-stage container for the frontend service · `frontend/Dockerfile`
- [Backend API](https://github.com/adityacodes-root/devops-project/blob/main/backend/app/main.py): FastAPI · Python API service · `backend/app/main.py`
- [Backend image](https://github.com/adityacodes-root/devops-project/tree/main/backend/Dockerfile): container build · Multi-stage container for the backend service · `backend/Dockerfile`

### Infrastructure

Terraform-managed cloud resources and runtime

- [AWS stack](https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/main.tf): Terraform env · AWS deployment boundary · `terraform/aws/main.tf`
- [Networking](https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/vpc.tf): AWS VPC · VPC and security boundary · `terraform/aws/vpc.tf`
- [ECS/Fargate](https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/ecs.tf): AWS runtime · Container orchestration for frontend and backend · `terraform/aws/ecs.tf`
- [Load balancer](https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/alb.tf): AWS ALB · Public traffic entry and routing · `terraform/aws/alb.tf`
- [Secrets](https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/secrets.tf): AWS Secrets Manager · Injected runtime secrets · `terraform/aws/secrets.tf`
- [Monitoring](https://github.com/adityacodes-root/devops-project/blob/main/terraform/aws/monitoring.tf): CloudWatch · Logs, dashboards, and alerts · `terraform/aws/monitoring.tf`
- [GCP stack](https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/main.tf): Terraform env · GCP deployment boundary · `terraform/gcp/main.tf`
- [Cloud Run](https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/cloudrun.tf): GCP runtime · Managed container runtime for services · `terraform/gcp/cloudrun.tf`
- [Secrets](https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/secrets.tf): Secret Manager · Injected runtime secrets · `terraform/gcp/secrets.tf`
- [Monitoring](https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/monitoring.tf): Cloud Monitoring · Service health and error observability · `terraform/gcp/monitoring.tf`

### Delivery

CI/CD and container build pipeline

- [CI](https://github.com/adityacodes-root/devops-project/blob/main/.github/workflows/ci.yml): GitHub Actions · Test and build validation on develop · `.github/workflows/ci.yml`
- [CD](https://github.com/adityacodes-root/devops-project/blob/main/.github/workflows/cd.yml): GitHub Actions · Build, push, and deploy on main · `.github/workflows/cd.yml`
- [Remote state](https://github.com/adityacodes-root/devops-project/blob/main/terraform/gcp/backend.tf): state backend · Shared remote Terraform state · `terraform/gcp/backend.tf`

## Connections

- Browser → Frontend: uses · Browser loads the Next.js app
- Frontend → Backend API: calls · Frontend fetches application data from the API
- Frontend → Frontend image: packaged as · Frontend deploys as a container image
- Backend API → Backend image: packaged as · Backend deploys as a container image
- AWS stack → Networking: defines · Core AWS networking boundary
- AWS stack → ECS/Fargate: defines · AWS container orchestration
- AWS stack → Load balancer: defines · Public routing layer
- AWS stack → Secrets: defines · AWS secret injection
- AWS stack → Monitoring: defines · AWS observability
- Load balancer → Frontend: routes to · Public requests reach the frontend service
- ECS/Fargate → Frontend image: runs · Frontend image runs on ECS/Fargate
- ECS/Fargate → Backend image: runs · Backend image runs on ECS/Fargate
- Secrets → Backend API: injects · Backend runtime configuration comes from secrets
- Monitoring → ECS/Fargate: watches · Monitors container services
- GCP stack → Cloud Run: defines · GCP managed container runtime
- GCP stack → Secrets: defines · GCP secret injection
- GCP stack → Monitoring: defines · GCP observability
- Cloud Run → Frontend image: runs · Frontend image runs on Cloud Run
- Cloud Run → Backend image: runs · Backend image runs on Cloud Run
- Secrets → Backend API: injects · Backend runtime configuration comes from secrets
- Monitoring → Cloud Run: watches · Monitors managed services
- CI → Frontend: tests · Validates frontend code
- CI → Backend API: tests · Validates backend code
- CI → Frontend image: builds · Checks frontend image build
- CI → Backend image: builds · Checks backend image build
- CD → Frontend image: builds/pushes · Produces the deployable frontend image
- CD → Backend image: builds/pushes · Produces the deployable backend image
- CD → AWS stack: applies · Deploys AWS infrastructure with Terraform
- CD → GCP stack: applies · Deploys GCP infrastructure with Terraform
- Remote state → AWS stack: stores state · Remote state backend for AWS deployments
- Remote state → GCP stack: stores state · Remote state backend for GCP deployments
