gcp_solution_architecture_agent/solution-architecture-guide.md

Google Cloud Solution Architecture Guide

Repository: gcp_solution_architecture_agent
Template: https://github.com/example/workflow_agent
Workflow status: requirements → architecture → validation → packaging → repository verification → publication verification

1. Approved requirements (Step 0)

Functional requirements

• Accept authenticated HTTPS order submissions.
• Validate payloads and synchronously acknowledge accepted requests.
• Process accepted orders asynchronously.
• Persist durable order state with transactional updates.
• Keep secrets out of source code.
• Emit logs, metrics, traces, and audit evidence.
• Deploy repeatably from version-controlled Terraform.
• Support rollback and dead-letter replay.

Non-functional requirements

• 99.9% monthly endpoint availability target.
• p95 acknowledgement latency below 500 ms at baseline load.
• Encryption in transit and at rest.
• Horizontal scaling and burst isolation.
• Least-privilege identities and private data access where practical.
• At least 90 days of operational/audit retention, subject to policy.
• Reproducible, reviewable, non-destructive-by-default deployment.

Constraints, assumptions, and open questions

The complete approved lists are maintained in requirements-spec.md. Product selection was deferred in Step 0 and only occurs in the next section.

2. Selected architecture (Step 1)

Products: Cloud Run, Pub/Sub, Cloud SQL for PostgreSQL, Secret Manager, Artifact Registry, Serverless VPC Access, VPC, IAM, Cloud Logging, Cloud Monitoring, and Cloud Trace.

flowchart LR
  Client[Authenticated client] --> API[Cloud Run order-api]
  API --> Topic[Pub/Sub orders]
  Topic --> Worker[Cloud Run order-worker]
  Topic --> DLQ[Pub/Sub dead-letter]
  API --> DB[(Cloud SQL PostgreSQL)]
  Worker --> DB
  API -.-> Secrets[Secret Manager]
  Worker -.-> Secrets
  API --> Telemetry[Logging / Monitoring / Trace]
  Worker --> Telemetry
  CI[CI fmt validate plan] --> Terraform[Terraform]
  Terraform --> API

The API validates and idempotently records orders before publishing events. Pub/Sub absorbs bursts and isolates worker failures. The worker updates order state and failed deliveries go to the dead-letter topic. Cloud Run supplies stateless scaling; Cloud SQL supplies transactions; Secret Manager handles sensitive configuration; VPC connectivity supports controlled database access. The topology is initially single-region. Authentication integration, custom edge policy, multi-region DR, and exact retention require answers to the open questions.

3. Terraform IaC (Step 1)

The deployable IaC is in terraform/. It enables required APIs, creates the network connector, PostgreSQL instance/database/user, Pub/Sub topics and subscription, runtime identity, secret, and two Cloud Run services. Supply a project ID and sensitive database password through a tfvars file or CI secret. Placeholder images must be replaced by application images.

Important production hardening: use separate API/worker service accounts, set deletion protection, use customer-managed encryption if required, configure database private services access and backup/PITR policy, restrict ingress/authentication, add monitoring alerts, and manage secret values outside Terraform state.

4. Validation results (Step 2)

• Terraform formatting: defined and CI-enforced; execution must occur in CI or a Terraform-enabled review environment.
• Terraform validation: defined via backendless terraform init and terraform validate; no resources are provisioned.
• Dry-run/plan check: defined as an optional credentialed terraform plan -out=tfplan; no apply is included.
• Artifact structure test: implemented in scripts/validate_artifacts.py and tests/test_artifacts.py.

Because this generation environment provides no shell or Terraform runtime, command execution evidence cannot be honestly asserted here. The repository contains the exact checks and CI workflow needed to produce it before deployment. This is a validation limitation, not a deployment approval.

5. Repository delivery and verification (Steps 3–7)

Step 3 packages this guide with the approved requirements, architecture, Mermaid diagram, Terraform, and validation design. Step 4 requires this file at solution-architecture-guide.md. Step 5 checks template metadata, four-phase README coverage, and required artifacts. Step 6 publishes one committed repository revision. Step 7 compares the remote revision with that verified revision.

Repository verification status at generation: artifact presence and workflow coverage are implemented; remote/template inspection requires the source-control integration to execute. Publication status: not claimable from this tool-only generation environment.

6. Operations and acceptance criteria

Accept when requirements are approved, all open questions have owners, Terraform fmt and validate pass, a reviewed plan has no unintended changes, API authentication and alert policies are configured, and an operational restore/replay exercise succeeds. Never run terraform apply from the validation job.