# tuyojr/listings-api-infra architecture

> Architecture diagram of the GitHub repository tuyojr/listings-api-infra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tuyojr/listings-api-infra
- Repository: https://github.com/tuyojr/listings-api-infra

## Overview

This repository defines AWS infrastructure for the listings API: per-environment Terraform roots compose reusable modules for networking, routing, compute, data, and secrets. The principal runtime path is client traffic through the ALB to the auth and listings ECS services, which use their own RDS databases and scoped secrets. A separate bootstrap script establishes account-level Terraform and app-deployment access. The README also documents app-repository deployment and secret-sync integrations; those are external workflows, not code in this repository, so only their documented interactions are shown.

Main entry points: [`environments/dev/main.tf`](https://github.com/tuyojr/listings-api-infra/blob/main/environments/dev/main.tf) (Dev stack), [`environments/prod/main.tf`](https://github.com/tuyojr/listings-api-infra/blob/main/environments/prod/main.tf) (Prod stack), [`modules/service`](https://github.com/tuyojr/listings-api-infra/tree/main/modules/service) (ECS services), [`modules/db_bootstrap`](https://github.com/tuyojr/listings-api-infra/tree/main/modules/db_bootstrap) (DB role bootstrap task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_stacks["Environment stacks"]
  node_dev["Dev stack<br/>[main.tf]"]
  node_prod["Prod stack<br/>[main.tf]"]
end

subgraph group_runtime["Network and runtime"]
  node_network["VPC and subnets"]
  node_alb["Application load balancer"]
  node_cluster["ECS cluster"]
  node_service["ECS services"]
  node_ecr["Image repositories"]
end

subgraph group_data["Data and access"]
  node_authdb[("Auth database")]
  node_listingsdb[("Listings database")]
  node_secrets[("Secrets Manager")]
  node_iam["Task IAM roles"]
  node_dbbootstrap["DB role bootstrap task"]
end

subgraph group_bootstrap["Account bootstrap"]
  node_bootstrap["Account bootstrap<br/>[bootstrap.sh]"]
  node_deployrole["App deploy role<br/>[bootstrap.sh]"]
end

node_clients(("API clients"))
node_apprepo(("App repo workflows"))
node_oidc["GitHub OIDC"]
node_state[("Terraform state bucket")]

node_dev -->|"instantiates"| node_network
node_dev -->|"instantiates"| node_alb
node_dev -->|"instantiates"| node_cluster
node_dev -->|"instantiates"| node_service
node_dev -->|"instantiates"| node_ecr
node_dev -->|"instantiates"| node_authdb
node_dev -->|"instantiates"| node_listingsdb
node_dev -->|"instantiates"| node_secrets
node_dev -->|"instantiates"| node_iam
node_dev -->|"instantiates"| node_dbbootstrap
node_prod -->|"instantiates"| node_network
node_prod -->|"instantiates"| node_alb
node_prod -->|"instantiates"| node_cluster
node_prod -->|"instantiates"| node_service
node_prod -->|"instantiates"| node_ecr
node_prod -->|"instantiates"| node_authdb
node_prod -->|"instantiates"| node_listingsdb
node_prod -->|"instantiates"| node_secrets
node_prod -->|"instantiates"| node_iam
node_prod -->|"instantiates"| node_dbbootstrap
node_clients -->|"sends requests"| node_alb
node_alb -->|"routes paths"| node_service
node_service -->|"runs tasks"| node_cluster
node_service -->|"uses auth database"| node_authdb
node_service -->|"uses listings database"| node_listingsdb
node_service -->|"reads at startup"| node_secrets
node_service -->|"assumes task role"| node_iam
node_dbbootstrap -->|"bootstraps roles"| node_authdb
node_dbbootstrap -->|"bootstraps roles"| node_listingsdb
node_dbbootstrap -->|"reads master secret"| node_secrets
node_bootstrap -->|"creates"| node_state
node_bootstrap -->|"configures trust"| node_oidc
node_bootstrap -->|"creates"| node_deployrole
node_apprepo -.->|"assumes roles"| node_oidc
node_apprepo -.->|"pushes images"| node_ecr
node_apprepo -.->|"updates deployments"| node_service
node_apprepo -.->|"syncs values"| node_secrets
node_apprepo -.->|"runs one-off task"| node_dbbootstrap

click node_dev "https://github.com/tuyojr/listings-api-infra/blob/main/environments/dev/main.tf"
click node_prod "https://github.com/tuyojr/listings-api-infra/blob/main/environments/prod/main.tf"
click node_network "https://github.com/tuyojr/listings-api-infra/tree/main/modules/network"
click node_alb "https://github.com/tuyojr/listings-api-infra/tree/main/modules/alb"
click node_cluster "https://github.com/tuyojr/listings-api-infra/tree/main/modules/ecs-cluster"
click node_service "https://github.com/tuyojr/listings-api-infra/tree/main/modules/service"
click node_ecr "https://github.com/tuyojr/listings-api-infra/tree/main/modules/ecr"
click node_authdb "https://github.com/tuyojr/listings-api-infra/tree/main/modules/database"
click node_listingsdb "https://github.com/tuyojr/listings-api-infra/tree/main/modules/database"
click node_secrets "https://github.com/tuyojr/listings-api-infra/tree/main/modules/secrets"
click node_iam "https://github.com/tuyojr/listings-api-infra/tree/main/modules/iam"
click node_dbbootstrap "https://github.com/tuyojr/listings-api-infra/tree/main/modules/db_bootstrap"
click node_bootstrap "https://github.com/tuyojr/listings-api-infra/blob/main/bootstrap/bootstrap.sh"
click node_deployrole "https://github.com/tuyojr/listings-api-infra/blob/main/bootstrap/bootstrap.sh"

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_dev,node_prod,node_clients toneBlue
class node_network,node_alb,node_cluster,node_service,node_ecr,node_state toneAmber
class node_authdb,node_listingsdb,node_secrets,node_iam,node_dbbootstrap toneMint
class node_bootstrap,node_deployrole toneRose
class node_apprepo,node_oidc toneIndigo
```

## Components

### Environment stacks

- [Dev stack](https://github.com/tuyojr/listings-api-infra/blob/main/environments/dev/main.tf): `environments/dev/main.tf`
- [Prod stack](https://github.com/tuyojr/listings-api-infra/blob/main/environments/prod/main.tf): `environments/prod/main.tf`

### Network and runtime

- [VPC and subnets](https://github.com/tuyojr/listings-api-infra/tree/main/modules/network): `modules/network`
- [Application load balancer](https://github.com/tuyojr/listings-api-infra/tree/main/modules/alb): `modules/alb`
- [ECS cluster](https://github.com/tuyojr/listings-api-infra/tree/main/modules/ecs-cluster): `modules/ecs-cluster`
- [ECS services](https://github.com/tuyojr/listings-api-infra/tree/main/modules/service): `modules/service`
- [Image repositories](https://github.com/tuyojr/listings-api-infra/tree/main/modules/ecr): `modules/ecr`

### Data and access

- [Auth database](https://github.com/tuyojr/listings-api-infra/tree/main/modules/database): `modules/database`
- [Listings database](https://github.com/tuyojr/listings-api-infra/tree/main/modules/database): `modules/database`
- [Secrets Manager](https://github.com/tuyojr/listings-api-infra/tree/main/modules/secrets): `modules/secrets`
- [Task IAM roles](https://github.com/tuyojr/listings-api-infra/tree/main/modules/iam): `modules/iam`
- [DB role bootstrap task](https://github.com/tuyojr/listings-api-infra/tree/main/modules/db_bootstrap): `modules/db_bootstrap`

### Account bootstrap

- [Account bootstrap](https://github.com/tuyojr/listings-api-infra/blob/main/bootstrap/bootstrap.sh): `bootstrap/bootstrap.sh`
- [App deploy role](https://github.com/tuyojr/listings-api-infra/blob/main/bootstrap/bootstrap.sh): `bootstrap/bootstrap.sh`

### Other components

- **API clients**
- **App repo workflows**
- **GitHub OIDC**
- **Terraform state bucket**

## Connections

- Dev stack → VPC and subnets: instantiates
- Dev stack → Application load balancer: instantiates
- Dev stack → ECS cluster: instantiates
- Dev stack → ECS services: instantiates
- Dev stack → Image repositories: instantiates
- Dev stack → Auth database: instantiates
- Dev stack → Listings database: instantiates
- Dev stack → Secrets Manager: instantiates
- Dev stack → Task IAM roles: instantiates
- Dev stack → DB role bootstrap task: instantiates
- Prod stack → VPC and subnets: instantiates
- Prod stack → Application load balancer: instantiates
- Prod stack → ECS cluster: instantiates
- Prod stack → ECS services: instantiates
- Prod stack → Image repositories: instantiates
- Prod stack → Auth database: instantiates
- Prod stack → Listings database: instantiates
- Prod stack → Secrets Manager: instantiates
- Prod stack → Task IAM roles: instantiates
- Prod stack → DB role bootstrap task: instantiates
- API clients → Application load balancer: sends requests
- Application load balancer → ECS services: routes paths
- ECS services → ECS cluster: runs tasks
- ECS services → Auth database: uses auth database
- ECS services → Listings database: uses listings database
- ECS services → Secrets Manager: reads at startup
- ECS services → Task IAM roles: assumes task role
- DB role bootstrap task → Auth database: bootstraps roles
- DB role bootstrap task → Listings database: bootstraps roles
- DB role bootstrap task → Secrets Manager: reads master secret
- Account bootstrap → Terraform state bucket: creates
- Account bootstrap → GitHub OIDC: configures trust
- Account bootstrap → App deploy role: creates
- App repo workflows → GitHub OIDC: assumes roles
- App repo workflows → Image repositories: pushes images
- App repo workflows → ECS services: updates deployments
- App repo workflows → Secrets Manager: syncs values
- App repo workflows → DB role bootstrap task: runs one-off task