# Steps 1–2 — selected architecture and validation design

## Selected Google Cloud products

- Cloud Run for the stateless HTTPS ingestion and worker services.
- Pub/Sub for durable asynchronous order events and a dead-letter topic.
- Cloud SQL for PostgreSQL for transactional order state.
- Secret Manager for database credentials and application secrets.
- Artifact Registry as the container image source.
- Cloud Logging, Cloud Monitoring, and Cloud Trace for observability.
- IAM and a dedicated service account for least-privilege workload identity.
- Serverless VPC Access and a VPC network for controlled access to the database.

## Mermaid diagram

```mermaid
flowchart LR
  Client[Authenticated client] --> Run[Cloud Run: order-api]
  Run --> Pub[Pub/Sub: orders]
  Pub --> Worker[Cloud Run: order-worker]
  Pub --> DLQ[Pub/Sub: orders-dead-letter]
  Run --> SQL[(Cloud SQL PostgreSQL)]
  Worker --> SQL
  Run -. secrets .-> SM[Secret Manager]
  Worker -. secrets .-> SM
  Run -. egress .-> VPC[Serverless VPC Access / VPC]
  Worker -. egress .-> VPC
  Run --> Obs[Logging / Monitoring / Trace]
  Worker --> Obs
  CI[CI: fmt, validate, plan] --> TF[Terraform]
  TF --> Run
```

## Architecture description

Clients call the authenticated `order-api` service. The API validates the request, writes an idempotency/order record to PostgreSQL, publishes an order event, and acknowledges the request. The worker consumes events independently, updates transactional state, and allows failed messages to be retained in the dead-letter topic for replay. Both services use separate runtime identities in production; the reference Terraform uses one explicitly scoped identity to keep the sample small and documents the split as a hardening action.

Cloud Run provides stateless horizontal scaling. Pub/Sub absorbs bursts and decouples downstream work. Cloud SQL supplies relational transactions; its private IP and VPC path are intended for production hardening. Secret Manager avoids embedding credentials. Managed logging, monitoring, and tracing provide operational evidence.

The initial topology is single-region. Multi-region failover, custom domain/edge policy, backup configuration, and application-level authentication integration remain deployment decisions because the open questions are unresolved.

## Validation design

`terraform fmt -check`, backendless `terraform init`, and `terraform validate` are run in CI. `scripts/validate_artifacts.py` checks that the requirements, architecture, Mermaid diagram, Terraform, and guide contain the required sections and that no product names occur in the product-neutral requirements section. No apply is used. A credentialed `terraform plan` is optional and must use a disposable plan file.