# Google Cloud solution architecture guide

## Scope and status
This guide packages manifest steps 0 through 7 for `gcp_solution_architecture_agent`, derived from the workflow-agent template. It is a reference baseline because no application-specific workflow request was supplied. Product selection was deferred during discovery and then made explicitly from the documented assumptions.

## Requirements
See [`docs/requirements.md`](docs/requirements.md). It contains functional requirements, non-functional requirements, constraints, assumptions, and open questions. The principal unresolved items are identity, scale/SLOs, data model, edge exposure, compliance, DR, and delivery governance.

## Selected products
Cloud Run, Pub/Sub, Cloud Storage, Firestore, VPC, Serverless VPC Access, Cloud Logging, Cloud Monitoring, Artifact Registry, IAM, and Service Usage.

## Architecture
```mermaid
flowchart LR
  C[External clients] -->|HTTPS| R[Cloud Run service]
  R --> F[(Firestore)]
  R --> S[(Cloud Storage)]
  R --> P[Pub/Sub topic]
  P --> W[Worker subscriber]
  P --> DLQ[Dead-letter topic]
  R --> L[Cloud Logging]
  R --> M[Cloud Monitoring]
  AR[Artifact Registry] --> R
  R -. private egress .-> VPC[VPC / Serverless VPC Access]
```

Clients use the HTTPS service. The service persists structured state and objects, emits events, and relies on a separate idempotent worker for asynchronous processing. The runtime has a dedicated identity, controlled egress, and managed encryption defaults. Public invocation is a deliberate baseline pending the ingress and identity answers in the open questions.

## Infrastructure as code
The deployable Terraform root is in [`terraform/`](terraform/). It enables APIs, creates a custom VPC/subnet and serverless connector, runtime service account, uniformly private object bucket, Firestore database, event/dead-letter topics, Artifact Registry repository, and Cloud Run service. Variables keep project, region, image, and labels configurable. No credentials or backend state are committed.

Apply only after review:
```bash
terraform -chdir=terraform init
terraform -chdir=terraform plan -var='project_id=PROJECT_ID' -var='container_image=IMAGE_URI'
terraform -chdir=terraform apply
```

## Validation
See [`validation-results.md`](validation-results.md). The repository supplies formatting, initialization without a backend, Terraform validation, an opt-in refresh-free plan, and Python artifact tests. Resource deployment is not part of validation. In this generation environment, these commands are **not_run** because required executables, provider downloads, and credentials are unavailable; CI must run them and record the results.

## Repository verification
- Step 4 guide persistence: represented by this non-empty file at the required path.
- Step 5 template/workflow conformance: represented by `workflow.yaml`, four phase entries, Terraform, diagram, requirements, and validation artifacts.
- Step 6 publication: performed by the repository generation commit.
- Step 7 remote verification: must compare the published revision with this file and `workflow.yaml` in the source-control system.

## Risks and follow-up
Confirm the open questions before production. Add Secret Manager, stronger ingress/edge controls, CMEK, backups, alert policies, quota budgets, dead-letter IAM, and multi-region recovery where required. The Cloud Run public invoker and one-year bucket deletion rule are baseline choices, not universal policy.