agents/gcp_solution_architecture_agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

decomposer: generate deliverable files for Discover and structure the solution's functional requirements, non-functional requirements, constraints, assumptions, and open questions without selecting cloud products.; Select Google Cloud products from the confirmed requirements and produce the solution architecture, Mermaid diagram, architecture description, and Terraform infrastructure-as-code.; Validate the Terraform infrastructure and architecture artifacts without deploying resources by running formatting checks, Terraform validation, and a dry-run or plan-oriented deployment check.; Package the approved requirements, architecture, Mermaid diagram, Terraform IaC, and validation results into solution-architecture-guide.md in the gcp_solution_architecture_agent repository.; Verify that the gcp_solution_architecture_agent repository contains the packaged solution-architecture-guide.md with the approved workflow outputs.; Verify that the repository is derived from the workflow_agent template and implements the complete four-phase Google Cloud solution architecture workflow alongside the packaged guide.; Publish the verified gcp_solution_architecture_agent repository with its completed workflow implementation and solution architecture guide.; Verify that the published repository revision contains the completed workflow implementation and solution architecture guide.
Some checks failed
validation / verify (push) Failing after 13s
Details

Browse Source
This commit is contained in:
demo-bot
2026-09-01 20:00:05 +00:00
parent f1d8e1ffcf
commit 7926fabc37
13 changed files with 341 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
solution-architecture-guide.md
View File

@@ -1,69 +1,49 @@
# Google Cloud Solution Architecture Guide
# Google Cloud solution architecture guide
**Repository:** `gcp_solution_architecture_agent`
**Template:** `https://github.com/example/workflow_agent`
**Status:** reference design; no resources provisioned.
## 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.
## 1. Approved requirements (Step 0)
## 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.
### Functional requirements
- Authenticated HTTPS stateless API.
- Transactional application persistence and indexed queries.
- Asynchronous domain events with retries and dead-letter handling.
- Operational logs, metrics, traces, and repeatable Terraform deployment.
### Non-functional requirements
- Managed horizontal scaling; 99.9% availability target; p95 normal reads under 500 ms.
- Regional initial deployment, encryption, least privilege, auditability, and no-resource validation.
### Constraints
Google Cloud target; Terraform IaC; parameterized project/region/environment; no committed secrets; one template-derived repository.
### Assumptions and open questions
See `requirements.md`. Production approval is conditional on confirming traffic, identity, RPO/RTO, data residency, retention, networking, CI identity, and event-schema answers.
Product selection was deferred in Step 0 and performed only after recording this baseline.
## 2. Product selection and architecture (Step 1)
Selected products are Cloud Run (API and worker), Cloud SQL for PostgreSQL, Pub/Sub, Artifact Registry, Secret Manager, Cloud Logging, Cloud Monitoring, Cloud Trace, IAM, and Service Usage. Cloud Run receives HTTPS traffic and emits events after database writes. Pub/Sub delivers at least once to a worker; the dead-letter topic captures exhausted delivery attempts. Cloud SQL is the system of record. Artifact Registry stores immutable image references. Secret Manager supplies secret references, while runtime and deployment identities are separated by IAM policy.
### Mermaid diagram
## 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[Client] -->|HTTPS + auth| API[Cloud Run API]
API --> DB[(Cloud SQL PostgreSQL)]
API --> BUS[Pub/Sub events]
BUS --> W[Cloud Run worker]
W --> DB
BUS -. exhausted retries .-> DLQ[Pub/Sub dead-letter topic]
API --> OBS[Cloud Logging / Monitoring / Trace]
W --> OBS
AR[Artifact Registry] -. immutable images .-> API
SM[Secret Manager] -. secret reference .-> API
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]
```
The full source is in `architecture.mmd`; Terraform is in `terraform/`. Terraform provisions foundational resources only and deliberately leaves application container builds, secret values, ingress policy, alert policies, database users, and migrations to deployment-specific hardening.
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.
## 3. Validation (Step 2)
## 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.
Validation is offline and plan-oriented; it must not create cloud resources.
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
```
| Check | Result |
|---|---|
| Terraform formatting (`terraform fmt -check -recursive`) | PASS by artifact review; run in CI/operator environment |
| Terraform initialization without backend (`terraform init -backend=false`) | PASS expected; provider download required |
| Terraform configuration validation (`terraform validate`) | PASS expected after provider initialization |
| Artifact/package validator (`python3 scripts/validate_artifacts.py`) | PASS |
| Provisioning/dry run | NOT EXECUTED; no credentials or cloud calls used |
## 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.
The exact commands are declared in `workflow.yaml` and `VALIDATION.md`. A real deployment must additionally run `terraform plan` with an approved variable file and review IAM, networking, SQL sizing, and costs.
## 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.
## 4. Delivery verification (Steps 3–7)
This guide packages the requirements, selected products, architecture narrative, diagram, Terraform, and validation record. Repository conformance is represented by `workflow.yaml`, which covers all four phases and maps manifest steps 0–7. Required artifacts are checked by `scripts/validate_artifacts.py` and `tests/test_package.py`. Publication should be a single commit containing this guide and all source artifacts; the commit hash is reported by the delivery automation.
## 5. Operations and risks
Set Cloud Run concurrency and minimum instances from measured load. Configure SQL HA, PITR, maintenance windows, and private IP before production. Grant Pub/Sub subscriber/publisher and Secret Manager accessor roles to dedicated service accounts, not broad project roles. Add SLO-based alerts, structured correlation IDs, trace propagation, log retention, vulnerability scanning, and an incident runbook. Event consumers must deduplicate by event ID. Open questions in `requirements.md` are release blockers for a production architecture decision.
## 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.