gcp_solution_architecture_agent/solution-architecture-guide.md

Google Cloud Solution Architecture Guide

Delivery status

This guide packages the approved discovery record, product architecture, diagram, Terraform, and pre-deployment validation procedure for gcp_solution_architecture_agent. It is a plan-only deliverable; it does not provision Google Cloud resources.

1. Requirements discovery (product selection deferred)

Functional requirements

• Accept authenticated HTTPS event requests.
• Validate, durably enqueue, and asynchronously process events.
• Persist raw events for replay and audit.
• Expose health and structured logs.
• Support environment-specific configuration.

Non-functional requirements

• At-least-once delivery with idempotent consumers.
• Regional high availability and independent scaling.
• Encryption in transit and at rest.
• 30-day configurable audit retention.
• Least privilege and observable failures.

Constraints and assumptions

The deployment targets an existing project, uses Terraform without apply, and receives its container image from external CI/CD. The workload is initially regional; the worker tolerates duplicates; product selection was deferred during discovery.

Open questions

Peak throughput and payload size, region/compliance and key policy, downstream destinations, and SLO/on-call thresholds remain to be confirmed before production hardening.

2. Selected Google Cloud products

• Cloud Run: authenticated HTTPS ingress and independently scalable worker runtime.
• Pub/Sub: durable asynchronous event transport and retry policy.
• Cloud Storage: retained raw-event replay and audit store.
• Artifact Registry: controlled container image repository.
• Cloud Logging and Cloud Monitoring APIs: operational telemetry foundation.
• IAM/service accounts: workload identity and least-privilege boundary.

3. Architecture diagram

flowchart LR
  Client[Authenticated producer] --> API[Cloud Run ingress]
  API --> Topic[Pub/Sub topic]
  Topic --> Sub[Pub/Sub subscription]
  Sub --> Worker[Cloud Run worker]
  API --> Raw[(Cloud Storage raw-event bucket)]
  Worker --> Raw
  Worker --> Downstream[External downstream systems]
  API --> Logs[Cloud Logging]
  Worker --> Logs
  Logs --> Monitor[Cloud Monitoring]
  API -. IAM .-> Identity[Dedicated runtime service account]
  Worker -. IAM .-> Identity

4. Architecture description

The ingress service validates a request, writes the original event to the retained bucket, and publishes an envelope. The worker acknowledges only after downstream processing succeeds. Event IDs are idempotency keys, so redelivery is safe. Cloud Run removes server management, Pub/Sub absorbs bursts, and Cloud Storage supplies replay. The Terraform creates APIs, identities, storage, messaging, an image repository, and a placeholder ingress service. Application behavior and image construction remain outside scope.

5. Infrastructure as code

The complete deployable Terraform is in terraform/:

• main.tf pins Google provider 6.x and creates the foundational resources.
• variables.tf makes project, region, environment, image, identity, retention, and scaling explicit.
• outputs.tf publishes the endpoint, bucket, and topic.
• terraform.tfvars.example documents required inputs.

Apply is intentionally not part of this repository's workflow.

6. Validation and findings

The repository provides scripts/validate.sh, which runs:

1. terraform fmt -check -diff
2. terraform init -backend=false -input=false
3. terraform validate
4. terraform plan -refresh=false -input=false -lock=false when required variables are supplied

The plan is saved only to /tmp and no resources are applied. The checked-in validation record marks execution as pending because this packaging environment does not claim access to Terraform or a Google Cloud project. Run the script in CI with Terraform 1.6.x, a pinned provider lock file generated by CI, and non-production plan credentials.

7. Verification record

• Guide persisted at solution-architecture-guide.md: yes.
• Template/workflow configuration: workflow.yaml declares all four phases and the source template.
• Required artifacts: requirements, architecture description, Mermaid diagram, Terraform, validation procedure, and this guide are present.
• Publication: repository publication is performed by the repository automation after review.

8. Production follow-up

Resolve the open questions, add explicit Pub/Sub-to-worker subscription IAM and dead-letter policy, decide whether customer-managed keys and private networking are mandatory, add SLO-based alert policies, and perform a security review before production use.