gcp_solution_architecture_agent/architecture.md

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

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.