45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# 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.
|