From e9246828b312acb93ba06b1176ad819ad3a5c881 Mon Sep 17 00:00:00 2001 From: Jonathan Boniface Date: Wed, 7 Oct 2026 13:59:09 +0100 Subject: [PATCH] feat: establish the Target architecture as a graph before code Design is now approved before any infrastructure code is written (ADR-0005). A new target-architect Specialist produces one graph of Elements, Relationships and Checks; the diagram is rendered from it, deployment guidance must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations carry ids in data files, and a submission with a gap in the Requirements chain is refused. Also in this commit: - Customer cases group Executions, with an intent history per case - lesson candidates are captured when an Execution ends - evaluation gains chain, verdict, judged and interactive checks, and per-case thresholds - Terraform providers are cached between checks - the requirements analyst proposes defaults instead of asking - the legacy-baseline case and the checks that only read it are removed - ADR-0006 (Change requests) accepted; ADR-0004 and ADR-0007 proposed - plans for iterations 4 to 7 under .agents/plans/ Unproven with a real model: no evaluation run has completed on this design. Co-Authored-By: Claude Opus 5.5 --- .agents/plans/README.md | 8 +- .../iter-02-solution-architect-agent/MAP.md | 2 +- .agents/plans/iter-03-kab-layout/MAP.md | 2 +- .../iter-04-learning-and-skills/DETAIL.md | 16 + .../plans/iter-04-learning-and-skills/MAP.md | 27 +- .../steps/step-1.md | 12 + .../steps/step-15.md | 19 + .../steps/step-16.md | 20 + .../steps/step-2.md | 10 + .../steps/step-3.md | 12 + .../steps/step-4.md | 15 + .../steps/step-5.md | 11 + .../steps/step-6.md | 6 + .../steps/step-7.md | 18 + .../steps/step-8.md | 36 + .agents/plans/iter-05-jev-decisions/DETAIL.md | 44 +- .agents/plans/iter-05-jev-decisions/MAP.md | 33 +- .../DETAIL.md | 87 +++ .../iter-06-target-architecture-graph/MAP.md | 89 +++ .../steps/step-1.md | 14 + .../steps/step-10.md | 12 + .../steps/step-11.md | 20 + .../steps/step-2.md | 17 + .../steps/step-3.md | 8 + .../steps/step-4.md | 8 + .../steps/step-5.md | 18 + .../steps/step-6.md | 10 + .../steps/step-7.md | 10 + .../steps/step-8.md | 9 + .../steps/step-9.md | 12 + .../plans/iter-07-change-requests/DETAIL.md | 60 ++ .agents/plans/iter-07-change-requests/MAP.md | 37 ++ .../iter-07-change-requests/steps/step-8.md | 13 + .dockerignore | 3 +- .env.example | 5 +- .gitignore | 3 + .scratch/solution-architect-agent/spec.md | 2 + CONTEXT.md | 46 +- README.md | 46 +- VALIDATION.md | 15 +- agents/decomposer.md | 1 + agents/describer.md | 4 +- agents/design-advisor.md | 4 +- agents/diagrammer.md | 11 - agents/iac-author.md | 8 +- agents/orchestrator.md | 10 +- agents/packager.md | 5 +- agents/partials/specialist-protocol.md | 6 +- agents/product-selector.md | 4 +- agents/requirements-analyst.md | 6 +- agents/target-architect.md | 17 + agents/validator.md | 7 +- app/a2a_server.py | 1 + app/adk/adk_runtime.py | 8 +- app/adk/fake_runtime.py | 93 +++ app/adk/runtime.py | 77 ++- app/agent.py | 36 +- app/config.py | 13 +- app/customer_case.py | 105 +++ app/main.py | 3 + app/nodes/execution_nodes.py | 207 +++++- app/presentation.py | 21 +- app/recorder.py | 23 + app/skills/agent_skills.py | 10 + app/states/execution_state.py | 52 ++ app/states/lessons.py | 125 ++++ app/tools/execution.py | 61 +- app/tools/local.py | 22 +- app/tools/pillars.py | 69 +- app/tools/toolkit.py | 40 +- app/workflows/chain.py | 336 ++++++++++ app/workflows/deliverables.py | 109 +++- app/workflows/execution_graph.py | 6 +- app/workflows/target_architecture.py | 283 ++++++++ deliverables/as-is/source-architecture.md | 15 - deliverables/as-is/source-architecture.mmd | 5 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 150 ----- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 150 ----- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 28 - .../as-is/source-architecture.mmd | 8 - .../guides/solution-architecture-guide.md | 233 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 150 ----- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 150 ----- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 150 ----- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 220 ------- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 18 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 150 ----- .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../as-is/source-architecture.md | 15 - .../as-is/source-architecture.mmd | 5 - .../guides/solution-architecture-guide.md | 217 ------ .../target/architecture.md | 21 - .../target/architecture.mmd | 6 - .../target/requirements.md | 44 -- .../validation/validation-results.md | 14 - .../guides/solution-architecture-guide.md | 217 ------ deliverables/target/architecture.md | 21 - deliverables/target/architecture.mmd | 6 - deliverables/target/requirements.md | 44 -- deliverables/validation/validation-results.md | 14 - ...langgraph-holds-state-adk-agents-reason.md | 2 + ...4-lessons-and-overlays-arrive-as-skills.md | 37 ++ ...arget-architecture-is-an-explicit-graph.md | 49 ++ ...equest-starts-from-a-baseline-execution.md | 40 ++ ...jev-is-the-orchestrators-decision-point.md | 55 ++ eval/datasets/solution_cases.json | 73 +++ eval/judge.py | 77 +++ eval/scoring.py | 227 ++++++- eval/solution_eval.py | 132 +++- providers/gcp.yaml | 16 +- scripts/validate_artifacts.py | 62 -- skills/iac-validation/SKILL.md | 4 + skills/requirements-chain/SKILL.md | 122 ++++ tests/a2a/test_server.py | 60 +- tests/agents/test_adk_engine.py | 12 +- tests/agents/test_roles.py | 10 +- tests/eval/test_scoring.py | 306 ++++++++- tests/execution/test_deliverables.py | 80 ++- tests/execution/test_engine.py | 389 +++++++++-- tests/execution/test_file_arguments.py | 10 +- tests/execution/test_ledger.py | 61 +- tests/execution/test_lessons.py | 239 +++++++ tests/execution/test_pillars.py | 173 ++++- tests/execution/test_presentation.py | 26 +- tests/execution/test_requirements_chain.py | 616 ++++++++++++++++++ tests/test_artifacts.py | 59 -- tests/test_package.py | 12 - tests/tools/test_local.py | 86 +++ workflow.yaml | 13 +- 586 files changed, 5166 insertions(+), 22432 deletions(-) create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-1.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-15.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-16.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-2.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-3.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-4.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-5.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-6.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-7.md create mode 100644 .agents/plans/iter-04-learning-and-skills/steps/step-8.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/DETAIL.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/MAP.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-1.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-10.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-11.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-2.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-3.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-4.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-5.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-6.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-7.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-8.md create mode 100644 .agents/plans/iter-06-target-architecture-graph/steps/step-9.md create mode 100644 .agents/plans/iter-07-change-requests/DETAIL.md create mode 100644 .agents/plans/iter-07-change-requests/MAP.md create mode 100644 .agents/plans/iter-07-change-requests/steps/step-8.md delete mode 100644 agents/diagrammer.md create mode 100644 agents/target-architect.md create mode 100644 app/customer_case.py create mode 100644 app/states/lessons.py create mode 100644 app/workflows/chain.py create mode 100644 app/workflows/target_architecture.py delete mode 100755 deliverables/as-is/source-architecture.md delete mode 100755 deliverables/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.md delete mode 100644 deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.md delete mode 100644 deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.mmd delete mode 100644 deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/requirements.md delete mode 100644 deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/validation/validation-results.md delete mode 100644 deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.md delete mode 100644 deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.md delete mode 100644 deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.mmd delete mode 100644 deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/requirements.md delete mode 100644 deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/validation/validation-results.md delete mode 100644 deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.md delete mode 100644 deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.md delete mode 100644 deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.mmd delete mode 100644 deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/requirements.md delete mode 100644 deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/validation/validation-results.md delete mode 100644 deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.md delete mode 100644 deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.md delete mode 100644 deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.mmd delete mode 100644 deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/requirements.md delete mode 100644 deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/validation/validation-results.md delete mode 100644 deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.md delete mode 100644 deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.md delete mode 100644 deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.mmd delete mode 100644 deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/requirements.md delete mode 100644 deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/validation/validation-results.md delete mode 100755 deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.md delete mode 100755 deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.md delete mode 100755 deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.mmd delete mode 100755 deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/requirements.md delete mode 100755 deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/validation/validation-results.md delete mode 100644 deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.md delete mode 100644 deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.md delete mode 100644 deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.mmd delete mode 100644 deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/requirements.md delete mode 100644 deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/validation/validation-results.md delete mode 100755 deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.md delete mode 100755 deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.md delete mode 100755 deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.mmd delete mode 100755 deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/requirements.md delete mode 100755 deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/validation/validation-results.md delete mode 100644 deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.md delete mode 100644 deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.md delete mode 100644 deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.mmd delete mode 100644 deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/requirements.md delete mode 100644 deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/validation/validation-results.md delete mode 100644 deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.md delete mode 100644 deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.md delete mode 100644 deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.mmd delete mode 100644 deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/requirements.md delete mode 100644 deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/validation/validation-results.md delete mode 100644 deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.md delete mode 100644 deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.md delete mode 100644 deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.mmd delete mode 100644 deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/requirements.md delete mode 100644 deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/validation/validation-results.md delete mode 100644 deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.md delete mode 100644 deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.md delete mode 100644 deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.mmd delete mode 100644 deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/requirements.md delete mode 100644 deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/validation/validation-results.md delete mode 100644 deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.md delete mode 100644 deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.md delete mode 100644 deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.mmd delete mode 100644 deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/requirements.md delete mode 100644 deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/validation/validation-results.md delete mode 100644 deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.md delete mode 100644 deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.md delete mode 100644 deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.mmd delete mode 100644 deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/requirements.md delete mode 100644 deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/validation/validation-results.md delete mode 100644 deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.md delete mode 100644 deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.md delete mode 100644 deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.mmd delete mode 100644 deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/requirements.md delete mode 100644 deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/validation/validation-results.md delete mode 100644 deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.md delete mode 100644 deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.md delete mode 100644 deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.mmd delete mode 100644 deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/requirements.md delete mode 100644 deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/validation/validation-results.md delete mode 100644 deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.md delete mode 100644 deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.md delete mode 100644 deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.mmd delete mode 100644 deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/requirements.md delete mode 100644 deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/validation/validation-results.md delete mode 100644 deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.md delete mode 100644 deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.md delete mode 100644 deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.mmd delete mode 100644 deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/requirements.md delete mode 100644 deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/validation/validation-results.md delete mode 100755 deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.md delete mode 100755 deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.md delete mode 100755 deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.mmd delete mode 100755 deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/requirements.md delete mode 100755 deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/validation/validation-results.md delete mode 100644 deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.md delete mode 100644 deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.md delete mode 100644 deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.mmd delete mode 100644 deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/requirements.md delete mode 100644 deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/validation/validation-results.md delete mode 100755 deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.md delete mode 100755 deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.md delete mode 100755 deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.mmd delete mode 100755 deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/requirements.md delete mode 100755 deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/validation/validation-results.md delete mode 100644 deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.md delete mode 100644 deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.md delete mode 100644 deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.mmd delete mode 100644 deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/requirements.md delete mode 100644 deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/validation/validation-results.md delete mode 100644 deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.md delete mode 100644 deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.md delete mode 100644 deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.mmd delete mode 100644 deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/requirements.md delete mode 100644 deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/validation/validation-results.md delete mode 100644 deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.md delete mode 100644 deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.md delete mode 100644 deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.mmd delete mode 100644 deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/requirements.md delete mode 100644 deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/validation/validation-results.md delete mode 100644 deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.md delete mode 100644 deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.md delete mode 100644 deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.mmd delete mode 100644 deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/requirements.md delete mode 100644 deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/validation/validation-results.md delete mode 100644 deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.md delete mode 100644 deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.md delete mode 100644 deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.mmd delete mode 100644 deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/requirements.md delete mode 100644 deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/validation/validation-results.md delete mode 100644 deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.md delete mode 100644 deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.md delete mode 100644 deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.mmd delete mode 100644 deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/requirements.md delete mode 100644 deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/validation/validation-results.md delete mode 100755 deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.md delete mode 100755 deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.md delete mode 100755 deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.mmd delete mode 100755 deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/requirements.md delete mode 100755 deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/validation/validation-results.md delete mode 100644 deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.md delete mode 100644 deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.md delete mode 100644 deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.mmd delete mode 100644 deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/requirements.md delete mode 100644 deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/validation/validation-results.md delete mode 100644 deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.md delete mode 100644 deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.md delete mode 100644 deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.mmd delete mode 100644 deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/requirements.md delete mode 100644 deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/validation/validation-results.md delete mode 100644 deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.md delete mode 100644 deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.md delete mode 100644 deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.mmd delete mode 100644 deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/requirements.md delete mode 100644 deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/validation/validation-results.md delete mode 100755 deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.md delete mode 100755 deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.md delete mode 100755 deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.mmd delete mode 100755 deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/requirements.md delete mode 100755 deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/validation/validation-results.md delete mode 100644 deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.md delete mode 100644 deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.md delete mode 100644 deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.mmd delete mode 100644 deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/requirements.md delete mode 100644 deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/validation/validation-results.md delete mode 100644 deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.md delete mode 100644 deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.md delete mode 100644 deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.mmd delete mode 100644 deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/requirements.md delete mode 100644 deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/validation/validation-results.md delete mode 100755 deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.md delete mode 100755 deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.md delete mode 100755 deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.mmd delete mode 100755 deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/requirements.md delete mode 100755 deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/validation/validation-results.md delete mode 100644 deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.md delete mode 100644 deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.md delete mode 100644 deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.mmd delete mode 100644 deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/requirements.md delete mode 100644 deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/validation/validation-results.md delete mode 100755 deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.md delete mode 100755 deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.md delete mode 100755 deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.mmd delete mode 100755 deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/requirements.md delete mode 100755 deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/validation/validation-results.md delete mode 100755 deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.md delete mode 100755 deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.md delete mode 100755 deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.mmd delete mode 100755 deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/requirements.md delete mode 100755 deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/validation/validation-results.md delete mode 100644 deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.md delete mode 100644 deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.md delete mode 100644 deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.mmd delete mode 100644 deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/requirements.md delete mode 100644 deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/validation/validation-results.md delete mode 100644 deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.md delete mode 100644 deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.md delete mode 100644 deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.mmd delete mode 100644 deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/requirements.md delete mode 100644 deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/validation/validation-results.md delete mode 100644 deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.md delete mode 100644 deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.md delete mode 100644 deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.mmd delete mode 100644 deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/requirements.md delete mode 100644 deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/validation/validation-results.md delete mode 100755 deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.md delete mode 100755 deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.md delete mode 100755 deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.mmd delete mode 100755 deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/requirements.md delete mode 100755 deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/validation/validation-results.md delete mode 100644 deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.md delete mode 100644 deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.md delete mode 100644 deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.mmd delete mode 100644 deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/requirements.md delete mode 100644 deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/validation/validation-results.md delete mode 100644 deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.md delete mode 100644 deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.md delete mode 100644 deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.mmd delete mode 100644 deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/requirements.md delete mode 100644 deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/validation/validation-results.md delete mode 100644 deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.md delete mode 100644 deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.md delete mode 100644 deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.mmd delete mode 100644 deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/requirements.md delete mode 100644 deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/validation/validation-results.md delete mode 100644 deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.md delete mode 100644 deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.md delete mode 100644 deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.mmd delete mode 100644 deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/requirements.md delete mode 100644 deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/validation/validation-results.md delete mode 100755 deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.md delete mode 100755 deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.md delete mode 100755 deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.mmd delete mode 100755 deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/requirements.md delete mode 100755 deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/validation/validation-results.md delete mode 100755 deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.md delete mode 100755 deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.md delete mode 100755 deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.mmd delete mode 100755 deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/requirements.md delete mode 100755 deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/validation/validation-results.md delete mode 100644 deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.md delete mode 100644 deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.md delete mode 100644 deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.mmd delete mode 100644 deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/requirements.md delete mode 100644 deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/validation/validation-results.md delete mode 100644 deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.md delete mode 100644 deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.md delete mode 100644 deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.mmd delete mode 100644 deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/requirements.md delete mode 100644 deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/validation/validation-results.md delete mode 100644 deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.md delete mode 100644 deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.md delete mode 100644 deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.mmd delete mode 100644 deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/requirements.md delete mode 100644 deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/validation/validation-results.md delete mode 100644 deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.md delete mode 100644 deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.md delete mode 100644 deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.mmd delete mode 100644 deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/requirements.md delete mode 100644 deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/validation/validation-results.md delete mode 100644 deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.md delete mode 100644 deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.md delete mode 100644 deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.mmd delete mode 100644 deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/requirements.md delete mode 100644 deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/validation/validation-results.md delete mode 100755 deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.md delete mode 100755 deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.md delete mode 100755 deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.mmd delete mode 100755 deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/requirements.md delete mode 100755 deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/validation/validation-results.md delete mode 100644 deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.md delete mode 100644 deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.md delete mode 100644 deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.mmd delete mode 100644 deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/requirements.md delete mode 100644 deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/validation/validation-results.md delete mode 100644 deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.md delete mode 100644 deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.md delete mode 100644 deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.mmd delete mode 100644 deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/requirements.md delete mode 100644 deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/validation/validation-results.md delete mode 100755 deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.md delete mode 100755 deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.md delete mode 100755 deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.mmd delete mode 100755 deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/requirements.md delete mode 100755 deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/validation/validation-results.md delete mode 100644 deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.md delete mode 100644 deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.md delete mode 100644 deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.mmd delete mode 100644 deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/requirements.md delete mode 100644 deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/validation/validation-results.md delete mode 100644 deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.md delete mode 100644 deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.md delete mode 100644 deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.mmd delete mode 100644 deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/requirements.md delete mode 100644 deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/validation/validation-results.md delete mode 100644 deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.md delete mode 100644 deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.md delete mode 100644 deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.mmd delete mode 100644 deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/requirements.md delete mode 100644 deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/validation/validation-results.md delete mode 100644 deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.md delete mode 100644 deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.md delete mode 100644 deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.mmd delete mode 100644 deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/requirements.md delete mode 100644 deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/validation/validation-results.md delete mode 100755 deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.md delete mode 100755 deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.md delete mode 100755 deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.mmd delete mode 100755 deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/requirements.md delete mode 100755 deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/validation/validation-results.md delete mode 100644 deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.md delete mode 100644 deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.md delete mode 100644 deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.mmd delete mode 100644 deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/requirements.md delete mode 100644 deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/validation/validation-results.md delete mode 100755 deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.md delete mode 100755 deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.md delete mode 100755 deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.mmd delete mode 100755 deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/requirements.md delete mode 100755 deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/validation/validation-results.md delete mode 100644 deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.md delete mode 100644 deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.md delete mode 100644 deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.mmd delete mode 100644 deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/requirements.md delete mode 100644 deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/validation/validation-results.md delete mode 100755 deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.md delete mode 100755 deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.mmd delete mode 100755 deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/guides/solution-architecture-guide.md delete mode 100755 deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.md delete mode 100755 deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.mmd delete mode 100755 deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/requirements.md delete mode 100755 deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/validation/validation-results.md delete mode 100644 deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.md delete mode 100644 deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.md delete mode 100644 deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.mmd delete mode 100644 deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/requirements.md delete mode 100644 deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/validation/validation-results.md delete mode 100644 deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.md delete mode 100644 deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.mmd delete mode 100644 deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/guides/solution-architecture-guide.md delete mode 100644 deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.md delete mode 100644 deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.mmd delete mode 100644 deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/requirements.md delete mode 100644 deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/validation/validation-results.md delete mode 100755 deliverables/guides/solution-architecture-guide.md delete mode 100755 deliverables/target/architecture.md delete mode 100755 deliverables/target/architecture.mmd delete mode 100755 deliverables/target/requirements.md delete mode 100755 deliverables/validation/validation-results.md create mode 100644 docs/adr/0004-lessons-and-overlays-arrive-as-skills.md create mode 100644 docs/adr/0005-the-target-architecture-is-an-explicit-graph.md create mode 100644 docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md create mode 100644 docs/adr/0007-jev-is-the-orchestrators-decision-point.md create mode 100644 eval/judge.py delete mode 100644 scripts/validate_artifacts.py create mode 100644 skills/requirements-chain/SKILL.md create mode 100644 tests/execution/test_lessons.py create mode 100644 tests/execution/test_requirements_chain.py delete mode 100644 tests/test_artifacts.py diff --git a/.agents/plans/README.md b/.agents/plans/README.md index c62367b..80d0ca7 100644 --- a/.agents/plans/README.md +++ b/.agents/plans/README.md @@ -8,9 +8,13 @@ One directory per iteration of this agent. Each holds the plan for that iteratio |---|---|---|---| | 1 | `wf-decompose-65ea49fc2d04/` | complete, superseded | The decomposer's scaffold: a linear four-phase pipeline of template functions. Its code was deleted in iteration 3 and survives only in git history. Generated by the platform decomposer; leave its files as written. | | 2 | `iter-02-solution-architect-agent/` | complete; step 9 was done in iteration 3 | The rebuild as a hierarchical ReAct agent: Orchestrator, one Specialist per Deliverable, Skills, provider bundle, A2A. | -| 3 | `iter-03-kab-layout/` | complete (uncommitted) | The container starts the new engine, the engine moved into the KAB workflow-agent folder layout, and the original pipeline was deleted. | -| 4 | `iter-04-learning-and-skills/` | planned | The enhancement backlog from the 2026-10-06 review: cheap fixes, the learning loop through Skills, overlay Skills, provider neutrality. | +| 3 | `iter-03-kab-layout/` | complete (commit `7ee49ab`) | The container starts the new engine, the engine moved into the KAB workflow-agent folder layout, and the original pipeline was deleted. | +| 4 | `iter-04-learning-and-skills/` | steps 1–8 and 15 built; no evaluation run has completed on them; 9 awaits the owner; 10–14 planned | The enhancement backlog from the 2026-10-06 review: cheap fixes, the learning loop through Skills, overlay Skills, provider neutrality. | | 5 | `iter-05-jev-decisions/` | planned, gated on open questions | Jev (a hosted decision model) for the agent's closed decisions: checks, routing, context selection. | +| 6 | `iter-06-target-architecture-graph/` | steps 1–10 built; step 11's evaluation run is outstanding, so unproven with real models | The Target architecture as one explicit graph of Elements, Relationships and Checks, established before infrastructure code, with validation as a verdict per Check. | +| 7 | `iter-07-change-requests/` | planned; ADR-0006 accepted 2026-10-07; follows iteration 6; its step 8 (removing `deliverables/cases/legacy-baseline/`) was done early on the owner's instruction | A user restates a request to say how requirements changed; a new Execution starts from a Baseline Execution of the same Customer case and delivers the updated architecture with what changed. | + +Numbers record when an iteration was planned, not the order to build in. Build iteration 6 before the remaining steps of iteration 4 (10 to 14) and before iteration 5: it changes the Deliverables, Phases and validation format they build on. Its `MAP.md` lists the effect on each of their steps. Two designs sit between iterations 1 and 2 and have no plan directory. Commit `a24a44e` wrapped the pipeline in a compatibility layer that imitated Google ADK without using it (deleted in iteration 3). `.scratch/phase-pipeline/spec.md` then designed a code-sequenced Phase pipeline; ADR-0002 reopened it before any of it was built, and its decision log (D1 to D46) explains how iteration 2's design was reached. diff --git a/.agents/plans/iter-02-solution-architect-agent/MAP.md b/.agents/plans/iter-02-solution-architect-agent/MAP.md index 2531f08..7f95faa 100644 --- a/.agents/plans/iter-02-solution-architect-agent/MAP.md +++ b/.agents/plans/iter-02-solution-architect-agent/MAP.md @@ -22,7 +22,7 @@ | 5 | ADK runtime and role files | complete | `f040493` | | 6 | Tools and remote MCP servers | complete | `ed104e5` | | 7 | Interfaces (A2A, `/generate`) | complete | `ad371b2` | -| 8 | Evaluation | complete, uncommitted | none | +| 8 | Evaluation | complete | `7ee49ab` | | 9 | Cleanup | done in iteration 3 | none | ## Dependency graph diff --git a/.agents/plans/iter-03-kab-layout/MAP.md b/.agents/plans/iter-03-kab-layout/MAP.md index 588ed0c..e5d6528 100644 --- a/.agents/plans/iter-03-kab-layout/MAP.md +++ b/.agents/plans/iter-03-kab-layout/MAP.md @@ -2,7 +2,7 @@ **Iteration:** 3, KAB layout **Intent:** Make the deployed container run the hierarchical Execution engine, and house that engine in the KAB workflow-agent folder layout (`app/agent.py`, `app/main.py`, `app/a2a_server.py`, `app/states/`, `app/nodes/`, `app/workflows/`), with the iteration 1 pipeline first parked under `app/legacy/` (steps 2 to 6) and then deleted (step 7). -**Branch:** `feat/solution-architect-agent` (all of this iteration is uncommitted as of 2026-10-06) +**Branch:** `feat/solution-architect-agent` (committed in `7ee49ab`, 2026-10-06) **This directory covers:** steps 1 to 7 ## Sources of truth diff --git a/.agents/plans/iter-04-learning-and-skills/DETAIL.md b/.agents/plans/iter-04-learning-and-skills/DETAIL.md index 023007e..eb66c1d 100644 --- a/.agents/plans/iter-04-learning-and-skills/DETAIL.md +++ b/.agents/plans/iter-04-learning-and-skills/DETAIL.md @@ -121,3 +121,19 @@ Every step ends with the full suite passing. Steps that change agent behaviour ( - **Where:** `providers/gcp.yaml`, `app/providers.py`, `app/workflows/deliverables.py`, `app/presentation.py`, `agents/iac-author.md`, `agents/validator.md`, `agents/design-advisor.md`. - **Timing:** Build when a second Cloud provider is planned. ADR-0002 says no provider interface exists in code until then. - **Acceptance criteria:** Pillar headings come from `pillar_skills`, guide sections from the bundle's `output_template`, and the IaC tool with its file contract from the bundle. `grep -rni "terraform" app/workflows app/nodes app/states` is empty, and no pillar or guide-section name appears as a literal in `app/workflows/deliverables.py`. + +## Step 15: Group Executions by Customer case + +- **Report ref:** none; requested by the owner on 2026-10-06 +- **Capability:** Everything under `deliverables/` is grouped by Customer case, so a case ties each request to the artefacts generated for it. +- **Rationale:** Outputs were keyed only by Execution id. Nothing on disk said which customer workload an Execution belonged to or what it had been asked. +- **Where:** `app/states/execution_state.py` (the case id rule and the paths), `ExecutionEngine.start` in `app/agent.py`, `_write_outputs` in `app/nodes/execution_nodes.py`, `app/main.py`, `app/a2a_server.py`, `eval/solution_eval.py`, `CONTEXT.md`. +- **Acceptance criteria:** Every Execution's files are under `deliverables/cases//executions//`. Each has a manifest naming the case, the request and every file. Each case has an index of its Executions and their requests. A case id that is not a safe slug is refused before anything runs. A Customer case never feeds one Execution into another. + +## Step 16: Cache Terraform providers between checks + +- **Report ref:** none; requested by the owner on 2026-10-07 to shorten a run +- **Capability:** A provider is downloaded once and reused by every later `terraform validate` and `plan`. +- **Rationale:** Each check runs `terraform init` in a new scratch directory, so every call downloaded its providers again. The setting `TF_PLUGIN_CACHE_DIR` existed and was unset by default. +- **Where:** `TerraformRunner` in `app/tools/local.py`, `app/config.py`, `.env.example`. +- **Acceptance criteria:** The cache is on by default and can be disabled. A second check of the same configuration does not download the provider. Concurrent checks cannot corrupt the cache. diff --git a/.agents/plans/iter-04-learning-and-skills/MAP.md b/.agents/plans/iter-04-learning-and-skills/MAP.md index 2ed7e6c..5cac6e4 100644 --- a/.agents/plans/iter-04-learning-and-skills/MAP.md +++ b/.agents/plans/iter-04-learning-and-skills/MAP.md @@ -2,8 +2,9 @@ **Iteration:** 4, learning and Skills **Intent:** Make the agent a learning, adaptable solution through Skills. Fix the cheap defects the 2026-10-06 review found, then close the loop so each Execution can improve the next through a reviewed Skill change, then let new standards, clients and Cloud providers arrive as Skills and configuration. -**Status:** planned; no step started -**This directory covers:** steps 1 to 14 +**Status:** steps 1 to 8 and 15 built; no evaluation run has completed on them (see `steps/step-8.md`); step 9 drafted and awaiting the owner; steps 10 to 14 planned. Steps 1 to 6 are in commit `7ee49ab`; 7, 8 and 15 are uncommitted. +**Changed by iteration 6:** `docs/adr/0005-the-target-architecture-is-an-explicit-graph.md` (accepted 2026-10-07) replaces the free-form `findings.json` of step 1 with a verdict per Check, remove the diagrammer, and add a Phase. Its plan is `../iter-06-target-architecture-graph/`, which lists the effect on each step here and should be built before steps 10 to 14. +**This directory covers:** steps 1 to 16 ## Sources of truth @@ -16,20 +17,22 @@ | Step | What | Group | Size | Status | |---|---|---|---|---| -| 1 | Structured validator findings | A | S | planned | -| 2 | Carry the draft through `needs_input` | A | S | planned | -| 3 | Reuse pillar advice across Revisions | A | S | planned | -| 4 | Single source for Deliverable contracts | A | S | planned | -| 5 | Cap parallel Specialists | A | S | planned | -| 6 | Orchestrator step order | A | S | planned | -| 7 | Capture lesson candidates | B | M | planned | -| 8 | Evaluation that can see improvement | B | M | planned | -| 9 | ADR: the lessons loop and overlay Skills | B | S | planned, owner's decision | +| 1 | Structured validator findings | A | S | replaced by iteration 6 step 9 (verdicts per Check) | +| 2 | Carry the draft through `needs_input` | A | S | complete | +| 3 | Reuse pillar advice across Revisions | A | S | built; evaluation run outstanding | +| 4 | Single source for Deliverable contracts | A | S | complete | +| 5 | Cap parallel Specialists | A | S | complete | +| 6 | Orchestrator step order | A | S | built; seen working in one stopped run, no completed evaluation | +| 7 | Capture lesson candidates | B | M | complete | +| 8 | Evaluation that can see improvement | B | M | built; thresholds and a judged run outstanding | +| 9 | ADR: the lessons loop and overlay Skills | B | S | drafted as `docs/adr/0004-lessons-and-overlays-arrive-as-skills.md`, status proposed; awaits the owner | | 10 | Lessons Skill and lesson curator | B | L | planned | | 11 | IaC patterns Skill | B | M | planned | | 12 | Overlay Skills and an organisation standards Skill | C | M | planned | | 13 | Trim Specialist context | C | M | planned | | 14 | Provider-owned contracts | C | M | planned | +| 15 | Group Executions by Customer case | added | S | complete | +| 16 | Cache Terraform providers between checks | added | S | complete | Size: S under a day, M a few days, L a week or more. Group A is cheap fixes that also create signal. Group B is the learning loop. Group C is adaptability. @@ -44,5 +47,7 @@ Size: S under a day, M a few days, L a week or more. Group A is cheap fixes that - Step 12: depends on step 9 - Step 13: depends on step 8 - Step 14: depends on step 4 +- Step 15: no dependencies (added on 2026-10-06 at the owner's request) +- Step 16: no dependencies (added on 2026-10-07 at the owner's request) Step 8 comes before steps 10, 11 and 13 so each of them can be shown to help: same quality, fewer Revisions, seconds or tokens. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-1.md b/.agents/plans/iter-04-learning-and-skills/steps/step-1.md new file mode 100644 index 0000000..49607ba --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-1.md @@ -0,0 +1,12 @@ +# Step 1 — Implementation Detail + +1. `validation_results` now requires a `findings.json` attachment (`FINDINGS_ATTACHMENT` in `app/workflows/deliverables.py`). +2. `check_findings` validates it at submission: a JSON list of objects with `deliverable` (a Deliverable kind), `severity` (`critical`, `high`, `medium`, `low`), `evidence` and `rule`. `[]` is valid and means a pass. Each problem is refused by field, for example `findings.json[1].severity: must be one of ...`. +3. `agents/validator.md` tells the validator to attach it; the format and an example live in `skills/iac-validation/SKILL.md` under "Reporting findings". +4. The file is written with the other attachments to `deliverables/executions//findings.json`. + +The check was added to `check_submission`, not to `app/tools/execution.py` as planned, so every contract rule stays in one function. + +Tests: `tests/execution/test_deliverables.py` (missing attachment, empty list, well-formed finding, malformed JSON, per-field problems). + +Not verified: no real-model run has confirmed the validator produces a well-formed file on its first submission. A malformed one costs a retry inside the validator's run, not a Revision. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-15.md b/.agents/plans/iter-04-learning-and-skills/steps/step-15.md new file mode 100644 index 0000000..19a29a6 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-15.md @@ -0,0 +1,19 @@ +# Step 15 — Implementation Detail + +1. **Customer case** is a glossary term (`CONTEXT.md`): a caller-supplied slug grouping the Executions for one customer workload. An Execution started without one belongs to `unassigned`, so every Execution sits under a case. +2. **Layout.** `deliverables/cases//executions//` holds an Execution's files. `execution_dir`, `case_dir` and `lessons_file` in `app/states/execution_state.py` are the only places these paths are built. +3. **`execution.json`** in each Execution folder names the case, the Execution, the Session, the Workflow request, and for each Deliverable its document and attachments. +4. **`intent/`** in each case folder records the customer's Intent and its history (`app/customer_case.py`). Each Workflow request is written as given to `intent/001.md`, `002.md` and so on when its Execution starts. `intent/history.json` lists every statement in order with the Execution it started, that Execution's status (`in_progress`, `completed`, `completed_with_warnings`) and the path to its files. This replaced the `case.json` index first built for this step; `execution.json` carries `intent_version`. +5. **Lesson candidates** are grouped the same way: `lessons/candidates//.json`, and the record carries `customer_case`. +6. **Callers.** `ExecutionEngine.start(customer_case=...)`; `/generate` takes `customer_case` in its body and answers 400 for an unsafe one; A2A reads `customer_case` from the message metadata. The evaluation uses each benchmark case's id. +7. **The case id** must be 1 to 64 lowercase letters, digits or hyphens, starting and ending with a letter or digit. It becomes a directory name, so anything else is refused before the Execution starts. +8. **Existing content moved.** `deliverables/as-is`, `target`, `validation`, `guides` and the 68 old `executions` folders are now under `deliverables/cases/legacy-baseline/`, with an `intent/` folder built from the request recorded in each old run's `requirements.md`, ordered by file time. `scripts/validate_artifacts.py` and `tests/test_artifacts.py` look there. + +Limits: + +- An Execution that ends with warnings writes no Deliverable files (an existing rule). Its request is still in the Intent history, with its status and no path, and its lesson candidates are grouped under its case. +- The 68 old runs were asked 12 different things but share one case, `legacy-baseline`. They can be split into a case per request from `intent/history.json` if that matters. +- `/generate`'s response keys are unchanged, so it does not return the case; `execution.json` does. +- The database rows carry the case only inside the status details, not as a column. + +Tests: `tests/execution/test_engine.py` (grouping, manifest, index, `unassigned`, refused ids), `tests/a2a/test_server.py` (`/generate`), `tests/execution/test_lessons.py`. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-16.md b/.agents/plans/iter-04-learning-and-skills/steps/step-16.md new file mode 100644 index 0000000..ae4f8d4 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-16.md @@ -0,0 +1,20 @@ +# Step 16 — Implementation Detail + +1. `TF_PLUGIN_CACHE_DIR` defaults to `.cache/terraform-plugins` under the repository root (already gitignored and kept out of the image build context). Set it empty to disable. `Settings.terraform_plugin_cache()` resolves it to an absolute path, since checks run in scratch directories. +2. `TerraformRunner` creates the directory on first use and passes it to Terraform. +3. It also sets `TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE=true`. A scratch directory has no dependency lock file, and without this Terraform downloads a cached provider again to verify it, which defeats the cache. +4. `terraform init` calls are serialised by a lock when the cache is in use, because Terraform's plugin cache is not safe for concurrent installs. + +Measured on 2026-10-07 with a one-resource configuration on the Google provider (`~> 6.0`), on this machine: + +| | Seconds per `terraform validate` | +|---|---| +| No cache | 7.3 to 7.8 | +| Cache, first use (downloads once) | 7.3 | +| Cache, later uses | 1.6 to 2.0 | + +So each check after the first saves about 5.5 seconds. The stopped run of 2026-10-06 made 7 validate calls in 16 minutes and more through its Revisions; at 12 to 15 calls a case, with the scoring's own check, that is roughly 1 to 1.5 minutes a case. The saving is real but small against a 35 minute run; it grows on a slower network. + +Costs: the cache holds each provider version once (117 MB for one Google provider version; the existing folder holds 600 MB across versions). In the container it is created under `/app/.cache` at run time and is lost with the container; pre-loading it into the image, or mounting a volume, would carry the saving across restarts and is not done. + +Tests: `tests/tools/test_local.py`, "the provider cache", using a stand-in terraform binary. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-2.md b/.agents/plans/iter-04-learning-and-skills/steps/step-2.md new file mode 100644 index 0000000..667ade8 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-2.md @@ -0,0 +1,10 @@ +# Step 2 — Implementation Detail + +1. `needs_input` accepts an optional `draft` and `attachments`; `NeedsInput` carries them (`app/adk/runtime.py`). +2. The Execution state holds `drafts` by Deliverable kind. `orchestrator_turn` stores a draft when it applies a `needs_input` outcome and drops it when that Deliverable is submitted. +3. A Specialist's context carries `draft` (`{content, attachments}` or `null`). +4. `agents/partials/specialist-protocol.md` tells Specialists to pass the complete draft with their confirmation question, to submit it unchanged once the latest answer approves it, and to apply requested changes to it. + +Test: `test_a_draft_sent_with_questions_comes_back_with_the_answer` in `tests/execution/test_engine.py` shows the second run receiving the draft and the submitted content equalling it. + +The draft is not shown to the user by the engine; the Specialist's question still carries its summary. Whether the full draft should appear in the prompt is an open product question. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-3.md b/.agents/plans/iter-04-learning-and-skills/steps/step-3.md new file mode 100644 index 0000000..b278a75 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-3.md @@ -0,0 +1,12 @@ +# Step 3 — Implementation Detail + +1. **Working memory.** Each Deliverable has a JSON-compatible working memory kept in Execution state (`working`, merged by key so parallel Specialists each write their own). `ToolFactory` now takes it as a third argument, so tools can remember across attempts. +2. **Pillar advice is remembered** under `pillar_advice` in the design recommendations' working memory (`app/tools/pillars.py`). +3. **Semantics of `consult_pillar_advisors`:** omit `pillars` to consult every pillar afresh; name `pillars` to re-consult only those, with the remembered advice returned for the rest under a heading marked "(from your earlier consultation)". Failed advice is never remembered. +4. `agents/design-advisor.md` tells the design advisor to name only the pillars its feedback touches when revising. + +Changed from the plan: the criterion "a changed brief for a pillar invalidates that pillar's stored advice" was not built. The brief is one text for all pillars and a model rewords it on every attempt, so hashing it would discard everything each time. Omitting `pillars` is the way to refresh all advice. + +Tests: `tests/execution/test_pillars.py` (subset re-consult, full refresh, failed advice not stored, and one through the engine showing advice surviving a Revision). + +Not verified: the evaluation run this step calls for. The saving depends on the design advisor following the new instruction; in case 01 it would cut up to 12 of 18 advisor runs. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-4.md b/.agents/plans/iter-04-learning-and-skills/steps/step-4.md new file mode 100644 index 0000000..a0f7564 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-4.md @@ -0,0 +1,15 @@ +# Step 4 — Implementation Detail + +1. `DeliverableSpec.contract()` returns the sections, attachments and table columns as data; every Specialist's context now carries it as `contract`. +2. Role files no longer list required headings. What remains in them is guidance the contract cannot express (what goes under a heading, verdicts, optional headings). +3. New contracts: + - `technical_decomposition`: a `Components` section and one table whose header names `component` and `requirement`. + - `architecture_description`: `Components` and `Flow` sections. Headings match by suffix, so "Data flow" and "Architecture components" satisfy them. + - Every required attachment must have content, which gives the diagram's `architecture.mmd` a minimum bar. +4. Tests share one contract-complete fixture, `sample_submission` in `app/adk/fake_runtime.py`. + +Two existing tests used an empty `terraform/variables.tf` as a fixture; they now use a non-empty one. + +Tests: `tests/execution/test_deliverables.py`, and `test_specialist_context_carries_its_contract` in `tests/execution/test_engine.py`. + +Not verified with real models: the two new section contracts change what the decomposer and describer must write. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-5.md b/.agents/plans/iter-04-learning-and-skills/steps/step-5.md new file mode 100644 index 0000000..f9af636 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-5.md @@ -0,0 +1,11 @@ +# Step 5 — Implementation Detail + +1. `RunLimiter` in `app/adk/runtime.py` caps agent runs in flight. `slot()` holds one; `lend()` gives the caller's slot up while its own fan-out runs. +2. `specialist_task` takes a slot for each Specialist run. The pillar tool lends the design advisor's slot and takes one per advisor, so the fan-out shares the cap and a cap of 1 cannot deadlock. +3. Setting `MAX_PARALLEL_SPECIALISTS` (default 4, as the spec's Risks section asked). `open_assembly` builds one limiter and gives it to both the engine and the tool factory. + +Changed from the plan: the cap is per engine process, not per Execution. Model rate limits apply to the project, so one cap across concurrent Executions is the stricter and more useful bound. + +An `ExecutionEngine` built without a limiter is uncapped, which keeps direct construction in tests unchanged. + +Tests: cap of 1 gives a peak of 1 and no cap gives a peak of 2 (`tests/execution/test_engine.py`); the fan-out under a held slot with a cap of 1 completes with a peak of 1 (`tests/execution/test_pillars.py`). diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-6.md b/.agents/plans/iter-04-learning-and-skills/steps/step-6.md new file mode 100644 index 0000000..2f04595 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-6.md @@ -0,0 +1,6 @@ +# Step 6 — Implementation Detail + +1. `agents/orchestrator.md`: "Validation found problems" is now step 3, above "A Phase is complete" (step 4) and "Work is ready" (step 5). +2. The step now says when it applies (validation results submitted and not yet approved), to read them first, and to send failed work back before asking the user to approve it. + +Not verified: the acceptance criterion needs a real-model evaluation run with a failing validation, showing a reopen before any Approval request for the validation Phase. No such run was made. The deterministic suite cannot test this, because the order is the model's choice. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-7.md b/.agents/plans/iter-04-learning-and-skills/steps/step-7.md new file mode 100644 index 0000000..1be9dcf --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-7.md @@ -0,0 +1,18 @@ +# Step 7 — Implementation Detail + +1. `app/states/lessons.py`: `collect_lesson_candidates` builds one record when an Execution ends, from what the Execution already holds. Candidate types: + - `revision`: each reopen, with its reason and who asked. + - `revision_limit`: a reopen refused at the cap. + - `change_request`: the user's feedback on a Phase, with the Deliverables in it. + - `finding`: each entry of every submitted `findings.json`, with the attempt it came from. + - `refusal`: each tool reply that did nothing (`REJECTION_PREFIXES`, now in `app/adk/runtime.py`), with role, tool and Deliverable. + - `unfinished`: a Specialist that stopped or spent its budget. +2. Refusals are captured in the nodes, not the runtime: `_noting_refusals` wraps each tool, so any runtime, the fake included, produces them. Specialist refusals travel in the outcome record; the Orchestrator's are kept in state under `refusals`. +3. The record names the Execution, its status, each role's Skills and a version per Skill. `skill_version` in `app/skills/agent_skills.py` is a 12-character content hash of the Skill's files. +4. It is written twice: through `ExecutionRecorder.record_lesson_candidates` (the database recorder stores it as an artifact of type `lesson_candidates`), and to `lessons/candidates/.json` under the output root. That directory is gitignored. + +Changed from the plan: the file is not inside `deliverables/executions//`. An Execution that ends with warnings must write no Deliverable files (an existing rule with a test), and those Executions are the ones most worth learning from. + +On "no secrets and no discovered cloud data": a refusal from a `cloud_read` tool keeps only the words before its first colon, and every message is cut at 500 characters. Revision reasons, user feedback and finding evidence are kept whole, so a record can quote the user and name resources in generated Terraform. Treat the files as client data. + +Tests: `tests/execution/test_lessons.py`. diff --git a/.agents/plans/iter-04-learning-and-skills/steps/step-8.md b/.agents/plans/iter-04-learning-and-skills/steps/step-8.md new file mode 100644 index 0000000..d879c62 --- /dev/null +++ b/.agents/plans/iter-04-learning-and-skills/steps/step-8.md @@ -0,0 +1,36 @@ +# Step 8 — Implementation Detail + +Built, with two acceptance criteria still open (listed at the end). + +1. **Structural checks added to every case** (`eval/scoring.py`): + - `components_trace_to_requirements`: every row of the decomposition's component table names a requirement. + - `no_blocking_findings`: the final `findings.json` holds no `critical` or `high` finding. +2. **Judged checks**, run with `--judge`: + - `pillar_checklists_covered`: each item of each pillar Skill's "Validation checklist" is put to the judge as a yes-or-no question against the design recommendations. The weakest pillar must reach 70%. + - `recommendations_quality`: four graded questions (specific, actionable, trade-offs, traceable); the mean must reach 0.67. + - `checklist_items` reads the checklists from the vendored Skills, nested bullets included, so a vendor sync updates the questions. +3. **Judge seam** (`eval/judge.py`): a `Judge` takes one document and a map of typed questions and returns a score from 0 to 1 each. `GeminiJudge` uses the bundle's default model, or `EVAL_JUDGE_MODEL`. The shape matches a decision model's, for iteration 5 step 10. One live call confirmed it works. +4. **Interactive case.** A case marked `"interactive": true` runs with a scripted user: `run_with_scripted_user` grants Approvals, denies cloud reads and answers questions by pattern. It adds the check `specialists_ask_before_submitting`. `case-04-interactive-web-app` is case 03 run this way. +5. **Thresholds.** A case may set `thresholds` for `revisions`, `seconds` and `tokens`. Exceeding one is printed as `REGRESSION`, listed in the report, and makes the exit code non-zero. It does not change the score. + +`automatic_reply` in `app/nodes/execution_nodes.py` lost its leading underscore so the evaluation can reuse it. + +Tests: `tests/eval/test_scoring.py`, with a fake judge. + +Open: + +- **Thresholds are not set.** They need a baseline per case from a completed run of the current code. None exists: see below. +- **No judged or interactive run yet.** +- **Judge stability** across repeated runs on the same output is unmeasured (iteration 5 step 10 names it). + +## The evaluation run of 2026-10-06 (stopped, no score) + +A three-case run was started on the code as of steps 1 to 6 and stopped by the owner after 35 minutes, during case 01. Cases 02 and 03 never started. Nothing was scored and no files were written, so it gives no baseline. What its log showed: + +- Seven Deliverables were submitted on their first attempt in about 15 minutes, including the decomposition and description under their new contracts (step 4). +- The Orchestrator reopened deployment guidance after each failed validation without first asking for Approval of the validation Phase, which is what step 6 intended. Observed three times in one case. +- No Revision of the design recommendations occurred, so step 3 was not exercised. +- Validation did not converge: three passes gave 4, then 7, then 5 different findings, and deployment guidance used all three Revisions. The four findings of the first pass were all still present after the first Revision. +- The Orchestrator stopped without calling a tool four times and was nudged; one such turn took 234 seconds. + +The non-convergence led to ADR-0005 (proposed): establish the Target architecture as an explicit graph with numbered Checks before code is written. diff --git a/.agents/plans/iter-05-jev-decisions/DETAIL.md b/.agents/plans/iter-05-jev-decisions/DETAIL.md index caf4034..8e26ddd 100644 --- a/.agents/plans/iter-05-jev-decisions/DETAIL.md +++ b/.agents/plans/iter-05-jev-decisions/DETAIL.md @@ -114,21 +114,31 @@ Rules for every step from 3 onward: - **Where:** `eval/scoring.py`, the curator from iteration 4 step 10. - **Acceptance criteria:** Rubric scores are stable across repeated runs on the same output. The curator receives candidates grouped and de-duplicated. -## Step 11: ADR: Orchestrator routing +## Step 11: ADR: Jev is the Orchestrator's decision point -- **Capability:** A recorded decision on whether code and Jev may take Orchestrator steps. -- **Rationale:** ADR-0003 rejected running the dependency graph with no Orchestrator model, so the top level stays ReAct. Step 12 moves the mechanical steps to code. -- **Evidence to bring:** results from steps 3 and 4, and the Orchestrator's 36 Pro requests and 53 thousand thinking tokens in case 03. -- **Acceptance criteria:** An accepted ADR that amends or confirms ADR-0003. If it confirms, step 12 is closed as not doing. +- **Capability:** A recorded decision that Jev proposes the Orchestrator's next action, code checks and carries it out, and a generative model only writes replies. +- **Rationale:** The owner's direction on 2026-10-07: use Jev as the decision point, not a different model. It replaces part of ADR-0003, which made the Orchestrator an ADK agent and rejected an Orchestrator without a model. +- **Where:** `docs/adr/0007-jev-is-the-orchestrators-decision-point.md`, with four points to confirm; a note on ADR-0003. +- **Acceptance criteria:** ADR-0007 is `accepted`, or amended with step 12 updated to match. -## Step 12: Orchestrator routing +## Step 12: The Orchestrator decides with Jev, with no language model -- **Report ref:** J1 -- **Capability:** The Orchestrator model runs only when judgement is needed. -- **Design:** Four of the seven steps in `agents/orchestrator.md` are decided by fields already in its context: pending questions, a Phase ready for Approval, ready work, packaging approved. Code takes those. Jev answers two judgements: a Noul for "did the user's latest message ask for changes?" and a Choice over the Deliverables for what to reopen. -- **Fallback:** the Orchestrator model, as today. -- **Where:** `orchestrator_turn` in `app/nodes/execution_nodes.py`. -- **Acceptance criteria:** Every Ledger rule still holds: the engine tests pass unchanged. On the cases, Orchestrator requests and seconds fall with the quality checks unchanged. +- **Report ref:** J1, widened by ADR-0007 +- **Capability:** Each Orchestrator turn is decided by the Ledger's rules and, where there is a choice or the user has spoken, by Jev. +- **Rationale:** In the stopped run of 2026-10-06 the Orchestrator took about 7 of 35 minutes and stalled four times. In case 03 it made 36 requests on the larger model. +- **Design:** + 1. A pure function lists the allowed next actions from the Ledger and the Execution's state. + 2. One allowed action is taken without a decision. + 3. Otherwise Jev is asked closed questions through the `Decider` from step 2: whether the user asked for a change and to which Deliverable; what follows a validation outcome; which allowed action is next. + 4. Code carries the decision out through `OrchestratorToolbox`, so the Ledger's rules are unchanged. + 5. Each decision is recorded in the Execution's state with its questions, answers and probabilities, and reused when a resumed Execution has unchanged input. + 6. A generative model writes only what the user reads: an Approval summary, or a question of the Orchestrator's own, from the decision and the data. It runs after the decision and cannot change it. A Revision's reason is the user's words or the failed Checks. + 7. A failed Jev call is recorded as a failure, distinct from an answer, and retried within a fixed budget before the fallback. +- **Pattern followed:** https://vercel.com/i/jev-agent-control. Its ownership split maps as: propose the next action, Jev; check permission, the Ledger; execute, the existing tools; update state, the Execution graph; explain the result, a generative model. Its specialist routing is not used, because the dependency graph fixes which Specialist produces each Deliverable. +- **Fallbacks:** Below the confidence threshold, an interactive Execution asks the user and a pre-approved one takes the safest allowed action with a warning. When Jev is unreachable, the fixed order of the seven steps is used and recorded. +- **Where:** `orchestrator_turn` in `app/nodes/execution_nodes.py`; `app/tools/execution.py`; `agents/orchestrator.md` becomes question wording and fixed text in a Skill or the bundle; `app/adk/roles.py` and `providers/gcp.yaml` no longer need an Orchestrator model. +- **What is sent to Jev:** state, not content: Deliverable names and statuses, Check ids and verdicts, the user's latest message. +- **Acceptance criteria:** The engine tests pass with a scripted `Decider` in place of the scripted Orchestrator model, covering every Ledger rule they cover today. No language model call chooses an action; the only Orchestrator model calls write user-facing text. A decision Jev proposes that the Ledger does not allow is refused and recorded. With no Jev key configured, an Execution still completes on the fixed order. On the evaluation cases, quality checks hold and Orchestrator seconds fall against the baseline. ## Step 13: Cloud-read call guard @@ -149,3 +159,13 @@ Rules for every step from 3 onward: - **Where:** `app/tools/mcp.py`, `await_user` in `app/nodes/execution_nodes.py`. - **Depends on step 1:** MCP results hold discovered cloud state. - **Acceptance criteria:** A test with a planted instruction in an MCP result shows it withheld and noted. + +## Step 15: Changes of meaning in a Change request + +- **Report ref:** none; from the "UI copy translation review" use case the owner named on 2026-10-07 +- **Capability:** A Change request follows through only the things whose meaning changed. +- **Rationale:** A Specialist revising from a Baseline rewords text it was not asked to change. Comparing text exactly would treat every rewording as a change; ignoring text would miss a dropped restriction, such as "only" removed from a requirement. +- **Design:** For each requirement, Element and Check whose text differs from the Baseline's, one Boolean question with the old and new text and its id: "Does the new text change what must be true?" A yes marks it changed, so the Requirements chain is followed from it; a no carries the Baseline's verdict forward. +- **Fallback:** Treat it as changed. +- **Where:** the graph comparison from iteration 7 step 4 (`app/workflows/target_architecture.py`), the change summary from iteration 7 step 6. +- **Acceptance criteria:** A reworded but equivalent Check is not reported as changed; a Check that lost or gained a condition is. Every decision is recorded with its probability in `changes.json`. diff --git a/.agents/plans/iter-05-jev-decisions/MAP.md b/.agents/plans/iter-05-jev-decisions/MAP.md index 65ff7f3..bc03800 100644 --- a/.agents/plans/iter-05-jev-decisions/MAP.md +++ b/.agents/plans/iter-05-jev-decisions/MAP.md @@ -2,8 +2,8 @@ **Iteration:** 5, Jev decisions **Intent:** Use Jev, a hosted decision model, for the agent's closed questions (yes or no, pick one, rate on a scale) so that large-model calls are kept for writing and reasoning. The aims are fewer tokens, faster turns, and checks the engine cannot make with string matching. -**Status:** planned; gated on step 1 -**This directory covers:** steps 1 to 14 +**Status:** planned; gated on step 1. Build `../iter-06-target-architecture-graph/` first: it removes the need for step 5 here and changes what step 4 checks. +**This directory covers:** steps 1 to 15 ## What Jev is @@ -26,10 +26,29 @@ Jev will be deployed separately and reached with an API key (owner, 2026-10-06). ## Sources of truth - https://www.langchain.com/blog/building-a-harness-with-jev and https://www.jevtypesafeai.com/use-cases (and `/docs` on that site). +- https://vercel.com/i/jev-agent-control: the agent-control pattern step 12 follows (decision model proposes, code checks and executes, a generative model explains). - Review report, section "Where Jev fits": https://claude.ai/code/artifact/16b37169-1554-4eb7-bfcb-254315fa0518. `Report ref` names its J-number. - `iter-04-learning-and-skills/`: several steps here build on steps there. - `docs/adr/0003-langgraph-holds-state-adk-agents-reason.md`: step 12 changes what it says about the Orchestrator. +## The capabilities the owner wants from Jev + +On 2026-10-07 the owner named the nine use cases at https://vercel.com/i/jev-use-cases as the capabilities to use. Each maps to this agent as follows. + +| Jev use case | Question type | What it is here | Step | +|---|---|---|---| +| Form routing | Choice | Read the user's message: an answer, a request for changes, or a new statement of Intent, and which Deliverable a change affects | 12 | +| Tool-call review (`clear` or `caution`) | Choice | Review each cloud-read call and `terraform_plan` before it runs; `caution` pauses for the user | 13 | +| Response model selection | Choice | Pick the model tier for each delegation from the bundle's list | 6 | +| Response evaluation | Boolean, Score | Judge a Deliverable at submission (does it address its task; is each Check verifiable as written), and score the evaluation's rubric | 4, 10 | +| Content moderation | Boolean | Flag text that breaks a written policy: requirements that name products; request or tool text that tries to instruct the agent | 4, 14 | +| UI copy translation review (did an edit change the meaning?) | Boolean | In a Change request, flag a requirement, Element or Check whose meaning changed against the Baseline, so only real changes are followed through | 15 | +| Ticket prioritization | Score | Rate how much a proposed addition or a failed Check matters, to order Revisions and lesson candidates | 10 | +| Document categorization | Choice | Sort lesson candidates by Deliverable for the curator | 10 | +| CSV column mapping | Choice | Suggest which requirement or recommendation a proposed addition serves, for confirmation; code still checks the link exists | 10 | + +The page's own cautions apply to every step: Jev does not write replies, so a generative model drafts messages; exact conditions (a Dependency is met, a file is attached, an id exists) stay deterministic checks in code; and a typed answer can still be wrong, so start where outcomes can be inspected and corrected, and record every decision. + ## Boundaries Jev answers closed questions. Writing Deliverables, grounding product choices and producing infrastructure code stay with the large models. Dependencies and Approvals stay rules in the Ledger. @@ -48,10 +67,11 @@ Jev answers closed questions. Writing Deliverables, grounding product choices an | 8 | Skill routing | J9 | planned | | 9 | In-run context compaction | J10 | planned | | 10 | Evaluation rubric and lesson triage | J8 | planned | -| 11 | ADR: Orchestrator routing | none | planned, owner's decision | -| 12 | Orchestrator routing | J1 | planned | +| 11 | ADR: Jev is the Orchestrator's decision point | none | drafted as `docs/adr/0007-jev-is-the-orchestrators-decision-point.md`, status proposed; awaits the owner | +| 12 | Jev proposes the Orchestrator's next action; a model only writes replies | J1 | planned; the owner's priority for this iteration (2026-10-07) | | 13 | Cloud-read call guard | J7 | planned | | 14 | Input guardrail | J11 | planned | +| 15 | Changes of meaning in a Change request | none | planned; needs iteration 7 | ## Dependency graph @@ -65,9 +85,10 @@ Jev answers closed questions. Writing Deliverables, grounding product choices an - Step 8: depends on step 2, iteration 4 step 12 - Step 9: depends on step 2 - Step 10: depends on step 2, iteration 4 step 7, iteration 4 step 8 -- Step 11: depends on step 4 having evaluation results -- Step 12: depends on step 2, step 11 +- Step 11: no dependencies +- Step 12: depends on step 2, step 11. Build it straight after step 2, ahead of steps 3 to 10. - Step 13: depends on step 2 - Step 14: depends on step 2 +- Step 15: depends on step 2, iteration 7 step 4 Steps 3 and 4 come first: they are small, need no ADR change, and target Revisions, where the tokens are. The Orchestrator is 11% of case 03's tokens; the IaC author and validator together used 1.43 million over 7 runs. diff --git a/.agents/plans/iter-06-target-architecture-graph/DETAIL.md b/.agents/plans/iter-06-target-architecture-graph/DETAIL.md new file mode 100644 index 0000000..03b0360 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/DETAIL.md @@ -0,0 +1,87 @@ +# Plan Detail + +Every step is built test-first with the fake runtime and ends with `pytest`, `ruff check .` and `mypy .` passing. File names for new attachments are proposals; keep them once a step uses them. + +## Step 1: Accept ADR-0005 + +- **Capability:** A recorded decision to build on. +- **The three points the owner confirms:** + 1. The user approves the Target architecture before code is written, which splits the solution architecture Phase and makes five Phases against the upstream Skill's four. + 2. A new Specialist produces the Target architecture. + 3. Code renders the diagram from the graph, and the diagrammer role is removed. +- **Acceptance criteria:** ADR-0005's status is `accepted`, or it is amended and this plan is updated to match before any other step starts. + +## Step 2: Identify requirements, components and recommendations by id + +- **Capability:** Stable ids at the start of the Requirements chain, as data. +- **Rationale:** A rule such as "every requirement has a Check" can only be enforced if requirements can be counted. Today requirements, components and recommendations exist only as prose. +- **Where:** `app/workflows/deliverables.py` (new required attachments and their checks), `agents/requirements-analyst.md`, `agents/decomposer.md`, `agents/design-advisor.md`, `agents/partials/specialist-protocol.md`. +- **Design:** + - `requirements` attaches `requirements.json`: a list of `{id, kind, text}` with `kind` functional or non-functional. + - `technical_decomposition` attaches `components.json`: a list of `{id, name, requirements: [ids]}`. This replaces the table contract from iteration 4 step 4. + - `design_recommendations` attaches `recommendations.json`: a list of `{id, pillar, text, components: [ids]}`. +- **Acceptance criteria:** Each attachment is refused when malformed, when an id repeats, or when it refers to an id that the Deliverable it depends on does not define. A requirement that no component serves is refused at the decomposition. + +## Step 3: The graph: format, parsing and structural rules + +- **Capability:** One definition of what a well-formed Target architecture is. +- **Where:** new `app/workflows/target_architecture.py`, pure and without I/O, like the Ledger. +- **Design:** `target-architecture.json` holds: + - `elements`: `{id, name, component, product, resource_type}`. + - `relationships`: `{id, from, to, kind}`. + - `checks`: `{id, applies_to, statement, source}`, where `applies_to` is an Element or Relationship id and `source` is a requirement or recommendation id. +- **Acceptance criteria:** Parsing refuses, with the offending id named: a repeated id; a Relationship whose `from` or `to` is not an Element; a Check whose `applies_to` is not in the graph; an Element with no Check; an empty `statement`. The module exposes the graph as typed data for steps 5, 7, 8 and 9. + +## Step 4: The Target architecture Deliverable, its Specialist and its Skill + +- **Capability:** A Deliverable that is the graph, produced by its own Specialist following a Skill. +- **Where:** `DeliverableKind.TARGET_ARCHITECTURE` in `app/workflows/deliverables.py`, depending on product selection and design recommendations; a new role file in `agents/`; a new Skill under `skills/` that defines the format and how to derive Elements, Relationships and Checks; `providers/gcp.yaml` (`role_skills`, model); `app/adk/roles.py` picks the role up from the dependency graph. +- **Rationale:** ADR-0002: how to model an architecture is behaviour and belongs in a Skill. The role file stays provider-neutral. +- **Who writes it:** the Specialist, never the user. The user's input is the Workflow request and their answers during requirements discovery; implementation-level detail is the agents' job, drawn from the pillar Skills and the provider's documentation. +- **Acceptance criteria:** The Deliverable requires `target-architecture.json`, checked by step 3 at submission. Its content is a readable summary with one section per Element. A Check's `statement` is written so that it can be verified from the infrastructure code alone, and the Skill says so with examples. + +## Step 5: Completeness: the Requirements chain is a submission rule + +- **Capability:** A Target architecture with a broken chain cannot be submitted. +- **Rationale:** This is the rule that makes the outcome understood up front. Without it the graph is one more document. +- **Where:** `check_submission` currently sees only the Deliverable being submitted. It needs the Deliverables it depends on: extend it and `specialist_tools` in `app/tools/execution.py` to pass them. +- **Acceptance criteria:** Submission is refused, naming each gap, when: a requirement id is the `source` of no Check, directly or through a component's Element; a component has no Element; a selected product appears on no Element; a recommendation is the `source` of no Check. A recommendation may be marked not applicable only with a stated reason, and that is listed for the user at Approval. + +## Step 6: Split the solution architecture Phase: design, then implementation + +- **Capability:** The user approves the Target architecture before code is written. +- **Where:** `PhaseId` and `DEPENDENCY_GRAPH` in `app/workflows/deliverables.py`; `agents/orchestrator.md`; `workflow.yaml` (its test will fail until updated); `app/card.py` derives from the graph; `app/presentation.py`; `eval/`; the spec's Phase table. +- **Design:** Design holds product selection, design recommendations and the Target architecture. Implementation holds the architecture description and the deployment guidance. +- **Acceptance criteria:** No Deliverable in implementation can start until design is approved (a Ledger test). The Approval prompt for design summarises the graph: counts of Elements, Relationships and Checks, and any recommendation marked not applicable. A pre-approved Execution passes through as today. + +## Step 7: The diagram is rendered from the graph + +- **Capability:** A diagram that cannot disagree with the architecture. +- **Where:** a renderer in `app/workflows/target_architecture.py` from Elements and Relationships to Mermaid; `architecture.mmd` is added to the Target architecture's attachments by the engine on submission; the `architecture_diagram` Deliverable, `agents/diagrammer.md` and its bundle entries are removed; `app/presentation.py` reads the diagram from the Target architecture so `/generate`'s keys are unchanged. +- **Acceptance criteria:** Rendering is deterministic and passes `mermaid_check` for any graph step 3 accepts, including names with characters Mermaid treats specially. Every Element and Relationship appears exactly once. The solution guide still carries the diagram in the template's section 4.2. + +## Step 8: Deployment guidance implements the graph + +- **Capability:** Code written against a known list, with each item accounted for. +- **Where:** `deployment_guidance` depends on the Target architecture; `agents/iac-author.md`; `skills/iac-validation/SKILL.md`; a required attachment `implementation.json`: for each Check id, the file and resource address that satisfies it. +- **Acceptance criteria:** Submission is refused when a Check id is missing from `implementation.json` or an id in it is not in the graph. The IaC author's context carries the graph, not the prose recommendations. `terraform_validate` must still pass before submission, as today. + +## Step 9: Validation gives a verdict per Check + +- **Capability:** A fixed bar: validation answers the graph's Checks and nothing else can fail the code. +- **Where:** `validation_results` requires `verdicts.json` in place of `findings.json`: for each Check id, `{verdict, evidence}` with `verdict` pass, fail or not verifiable, plus a separate list `proposed_additions` of `{statement, applies_to, reason}`. `agents/validator.md`, `skills/iac-validation/SKILL.md`, `app/states/lessons.py`, `eval/scoring.py`. +- **Acceptance criteria:** Submission is refused unless every Check has exactly one verdict with evidence. A proposed addition never counts as a failure. A `not verifiable` verdict is treated as a gap in the graph, not in the code. The dry-run result (`terraform validate`, and `plan` when permitted) is itself a Check on the deployment as a whole, so it has a verdict too. + +## Step 10: Revision routing: the code or the graph + +- **Capability:** Each validation outcome leads to exactly one kind of Revision. +- **Where:** `_orchestrator_context` in `app/nodes/execution_nodes.py` gives the Orchestrator the failed Check ids and the proposed additions; `agents/orchestrator.md`. +- **Design:** Failed Checks reopen the deployment guidance, with the failed ids as the reason. Proposed additions and `not verifiable` verdicts go to the user in an interactive Execution; in a pre-approved one the Orchestrator reopens the Target architecture only for an addition that names a requirement or recommendation id. Reopening the Target architecture returns the implementation Phase to draft and withdraws its Approval, by the Ledger's existing rule. +- **Acceptance criteria:** Engine tests show both routes. With unchanged code and an unchanged graph, a second validation pass has the same Check ids as the first: the list cannot grow. + +## Step 11: Evaluation: prove the loop converges + +- **Capability:** Evidence that the outcome is understood before code is written. +- **Where:** `eval/scoring.py`, `eval/solution_eval.py`, `eval/datasets/solution_cases.json`. +- **Design:** New checks: every requirement reaches at least one Check with a pass verdict; no Check is left failed or not verifiable; the diagram matches the graph. The report records, per case, the number of validation passes and the Check ids failing at each. +- **Acceptance criteria:** All benchmark cases complete and score at least 0.8. In each, the set of failing Check ids never grows from one validation pass to the next, and deployment guidance needs at most one Revision in at least two of the three cases. The thresholds left unset by iteration 4 step 8 are set from this run. The comparison with the stopped run of 2026-10-06 is written into this step's file. diff --git a/.agents/plans/iter-06-target-architecture-graph/MAP.md b/.agents/plans/iter-06-target-architecture-graph/MAP.md new file mode 100644 index 0000000..e0d8f87 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/MAP.md @@ -0,0 +1,89 @@ +# Plan Map + +**Iteration:** 6, the Target architecture graph +**Intent:** Establish the Target architecture as one explicit graph of Elements, Relationships and Checks before any infrastructure code is written, and derive and check every later Deliverable from it, so that the outcome is understood before code exists and validation has a fixed bar. +**Status:** steps 1 to 10 built and covered by the deterministic suite; nothing has run against a real model; step 11's evaluation run is on hold by the owner +**This directory covers:** steps 1 to 11 + +## Order of work + +Build this iteration before the remaining steps of iteration 4 (10 to 14) and before iteration 5. It changes Deliverables, Phases and the validation format that those steps build on. The effects on them are listed at the end of this file. + +## Sources of truth + +- `docs/adr/0005-the-target-architecture-is-an-explicit-graph.md`: the decision, its three points to confirm, and the rejected alternatives. Status `proposed`. +- `CONTEXT.md`: Target architecture, Element, Relationship, Check, Requirements chain. Use these words; "Dependency" stays the link between Deliverables. +- `iter-04-learning-and-skills/steps/step-8.md`, "The evaluation run of 2026-10-06": the evidence. Three validation passes gave 4, 7, then 5 different findings on the same Terraform. +- `docs/adr/0002-*.md`: the graph's format and how to write it are behaviour, so they live in a Skill; the engine only checks the result. + +## The flow this iteration builds + +```mermaid +flowchart TD + REQ([Workflow request]) --> R[Requirements] + R --> D[Technical decomposition] + D --> A1{{Approval: requirements discovery}} + A1 --> PS[Product selection] + PS --> DR[Design recommendations] + R --> DR + PS --> TA + DR --> TA[Target architecture: Elements, Relationships, Checks] + TA --> A2{{Approval: design}} + A2 --> DESC[Architecture description] + A2 --> IAC[Deployment guidance] + TA -.rendered by code.-> DIA[Architecture diagram] + IAC --> A3{{Approval: implementation}} + DESC --> A3 + A3 --> VAL[Validation: a verdict per Check] + VAL -->|a Check fails| IAC + VAL -->|the graph is missing something| TA + VAL -->|every Check passes| A4{{Approval: validation}} + A4 --> G[Solution guide] + G --> A5{{Approval: packaging}} +``` + +## Status + +| Step | What | Size | Status | +|---|---|---|---| +| 1 | Accept ADR-0005 | S | complete: accepted 2026-10-07 | +| 2 | Identify requirements, components and recommendations by id | M | complete | +| 3 | The graph: format, parsing and structural rules | M | complete | +| 4 | The Target architecture Deliverable, its Specialist and its Skill | M | complete; unproven with a real model | +| 5 | Completeness: the Requirements chain is a submission rule | M | complete | +| 6 | Split the solution architecture Phase: design, then implementation | M | complete | +| 7 | The diagram is rendered from the graph | S | complete | +| 8 | Deployment guidance implements the graph | M | complete | +| 9 | Validation gives a verdict per Check | M | complete | +| 10 | Revision routing: the code or the graph | S | complete; routing unproven with a real model | +| 11 | Evaluation: prove the loop converges | M | checks built; evaluation run outstanding (on hold by the owner) | + +Size: S under a day, M a few days. + +## Dependency graph + +- Step 1: no dependencies +- Step 2: depends on step 1 +- Step 3: depends on step 1 +- Step 4: depends on step 3 +- Step 5: depends on step 2, step 4 +- Step 6: depends on step 4 +- Step 7: depends on step 4 +- Step 8: depends on step 5 +- Step 9: depends on step 8 +- Step 10: depends on step 6, step 9 +- Step 11: depends on step 7, step 10 + +Steps 2 and 3 can be built side by side, as can 6 and 7. + +## Effects on other iterations + +- **Iteration 4 step 1** (`findings.json`): replaced by the verdicts of step 9 here. The free-form finding list goes. +- **Iteration 4 step 4** (contracts): the diagram's contract goes with the diagrammer; the decomposition's component table becomes data in step 2 here. +- **Iteration 4 step 6** (Orchestrator step order): rewritten by step 10 here. +- **Iteration 4 step 7** (lesson candidates): `finding` candidates become failed Checks and proposed additions. +- **Iteration 4 step 8** (evaluation): `no_blocking_findings` is rewritten against verdicts; the unset thresholds are set by step 11 here. +- **Iteration 4 step 11** (IaC patterns Skill): its patterns should be keyed by the product of an Element. +- **Iteration 4 step 13** (trim Specialist context): mostly achieved here, since later Specialists work from the graph. Re-scope it after step 11. +- **Iteration 5 step 5** (finding-to-Deliverable routing): no longer needed; a failed Check already names what it applies to. +- **Iteration 5 step 4** (semantic checks at submission): can judge whether each Check is verifiable as written. diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-1.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-1.md new file mode 100644 index 0000000..74d9da9 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-1.md @@ -0,0 +1,14 @@ +# Step 1 — Implementation Detail + +ADR-0005 was accepted by the owner on 2026-10-07 ("lets move forward with this", after reviewing the proposed case structure), with its three points as written: + +1. The user approves the Target architecture before code is written; the solution architecture Phase is split, making five Phases. +2. A new Specialist produces the Target architecture. +3. Code renders the diagram from the graph; the diagrammer role is removed. + +ADR-0006 (Change requests) was accepted in the same reply; it is built in iteration 7. + +Clarifications the owner gave before accepting, now in the ADR and the role files: + +- The graph is the Target architecture itself, not a build plan beside it. +- The user states Intent at a high level in the Workflow request. The agents derive every Element, Relationship and Check from the architecture framework and best practice; the user never writes the graph. diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-10.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-10.md new file mode 100644 index 0000000..280e0e8 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-10.md @@ -0,0 +1,12 @@ +# Step 10 — Implementation Detail + +1. The Orchestrator's context carries `validation`: the outcome of the submitted validation, or null before there is one. +2. `agents/orchestrator.md` step 3, "Validation decided", routes on it: + - failed Checks, or a failed dry-run: reopen the deployment guidance with each failed Check's id and evidence. + - otherwise, not-verifiable Checks or proposed additions: the Target architecture has a gap. Interactive: ask the user whether to revise it. Pre-approved: reopen it only for items whose reason names a requirement or recommendation id. + +The routing is the Orchestrator's choice, as ADR-0003 requires; the engine supplies the facts and the Ledger enforces what a reopen does. + +On "the list cannot grow": the verdict list is fixed by the graph, because every verdict must be on a Check and every Check must have one. With an unchanged graph, two validation passes cover the same ids by construction (`test_validation_gives_exactly_one_verdict_per_check`). + +Not verified: whether a real Orchestrator model follows the new routing. `test_the_orchestrator_is_told_what_validation_decided` covers the context and the Revision, with the reopen scripted. diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-11.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-11.md new file mode 100644 index 0000000..40ae7d0 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-11.md @@ -0,0 +1,20 @@ +# Step 11 — Implementation Detail + +Partly done. The checks are built; the evaluation run that this step exists for has not been made. + +Built in `eval/scoring.py`: + +- `requirements_chain_complete`: the delivered data files form a chain with no gap. +- `every_check_passes`: validation ended with no Check failed or not verifiable, and the dry-run not failed. +- `diagram_matches_graph`: the delivered diagram is exactly the rendering of the delivered graph. + +These replaced `components_trace_to_requirements` and `no_blocking_findings` from iteration 4 step 8. + +Outstanding, and why: + +- **No evaluation run.** The owner stopped the last run on 2026-10-06 and asked that no further cases start until they advise. Nothing in this iteration has run against a real model. +- **The acceptance criteria are therefore unmet:** all cases scoring at least 0.8, the failing-Check set never growing between passes, and at most one Revision of the deployment guidance in two of three cases. +- **Not built:** the per-case record of validation passes and the Check ids failing at each. The evaluation reads only the final verdicts today. +- **Thresholds** from iteration 4 step 8 are still unset. + +Do not mark this step complete until a run meets the criteria. (`legacy-baseline` was removed on 2026-10-07 on the owner's instruction, ahead of this.) diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-2.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-2.md new file mode 100644 index 0000000..2427b49 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-2.md @@ -0,0 +1,17 @@ +# Step 2 — Implementation Detail + +1. `app/workflows/chain.py` defines the data files and a checker for each. Each checker returns one entry per fault, so a Specialist can fix and resubmit. +2. New required attachments (`DATA_CHECKS` in `app/workflows/deliverables.py`): + - `requirements.json` on requirements: `{id, kind, text}`, kind functional or non_functional, ids unique. + - `components.json` on the technical decomposition: `{id, name, requirements}`. This replaced the component table contract from iteration 4 step 4. + - `products.json` on product selection: `{component, product}`, one for every component. + - `recommendations.json` on design recommendations: `{id, pillar, text, components}`. +3. `check_submission` takes the Deliverables being built on (`upstream`), so links are checked across Deliverables: a component may only serve a real requirement, a product may only be selected for a real component, a recommendation may only name real components. +4. The formats live in a new Skill, `skills/requirements-chain/SKILL.md`, assigned in `providers/gcp.yaml` to every role that writes or reads one. + +Changed from the plan: + +- `products.json` was added. The plan's rule "a selected product appears on no Element" needs the selection as data. +- Only functional requirements must be served by a component at the decomposition. A non-functional requirement often constrains the whole workload, so it is held to a stricter rule later: it must be the source of a Check (step 5). + +Tests: `tests/execution/test_requirements_chain.py`, "the links before the graph". diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-3.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-3.md new file mode 100644 index 0000000..269c318 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-3.md @@ -0,0 +1,8 @@ +# Step 3 — Implementation Detail + +1. `app/workflows/target_architecture.py`, pure and without I/O: `Element`, `Relationship`, `Check`, `NotApplicable`, `TargetArchitecture`, and `parse_graph`, which returns the graph or raises `GraphError` listing every fault. +2. The file is `target-architecture.json` with `elements`, `relationships`, `checks` and optional `not_applicable`. +3. Refused, with the id named: a repeated id; a Relationship whose `from` or `to` is not an Element; a Check that applies to nothing in the graph; an Element with no Check; a missing or empty field. +4. An Element's `component` is optional, for supporting Elements such as identities, keys and networks. + +Tests: `tests/execution/test_requirements_chain.py`, "the graph is well-formed". diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-4.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-4.md new file mode 100644 index 0000000..cdedf2d --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-4.md @@ -0,0 +1,8 @@ +# Step 4 — Implementation Detail + +1. `DeliverableKind.TARGET_ARCHITECTURE`, in the design Phase, depending on product selection and design recommendations. Its content needs `Elements`, `Relationships` and `Checks` sections; its attachment is the graph. +2. Role file `agents/target-architect.md`. In the bundle it loads the solution-architecture and requirements-chain Skills, reaches the documentation MCP server, and runs on the Pro model tier. +3. `skills/requirements-chain/SKILL.md` gives the graph's format and how to write a Check that can be verified from code, with verifiable and non-verifiable examples. +4. The role file states that implementation detail is the agent's job and the user stays at the level of Intent. + +Not verified: no real model has produced a Target architecture yet. Whether one can write Checks specific enough to verify, in one run and inside its tool budget, is the main risk of this iteration and is what step 11 measures. diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-5.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-5.md new file mode 100644 index 0000000..abca806 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-5.md @@ -0,0 +1,18 @@ +# Step 5 — Implementation Detail + +`chain_gaps` in `app/workflows/target_architecture.py` lists every place the Requirements chain stops; `check_target_architecture` runs it at submission, so a Target architecture with a gap is refused with each gap named. + +A gap is: + +- a component with no Element; +- a non-functional requirement that is the source of no Check; +- a functional requirement that is the source of no Check and is served by no component with an Element; +- a selected product that does not appear on its component's Element; +- a recommendation that is the source of no Check and is not listed under `not_applicable` with a reason; +- a Check whose `source` is not a requirement or recommendation, or an Element that realises something that is not a component. + +Recommendations marked not applicable are carried in the graph's summary and shown to the user at the design Approval. + +The rule checks that each link exists, not that it is right. A vague Check passes here and is caught later as `not_verifiable`, or by the user at Approval. + +Tests: `tests/execution/test_requirements_chain.py`, "the Requirements chain has no gap", including one through `submit_deliverable`. diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-6.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-6.md new file mode 100644 index 0000000..6b0e982 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-6.md @@ -0,0 +1,10 @@ +# Step 6 — Implementation Detail + +1. `PhaseId` has five members. `solution_architecture` is now the design Phase (product selection, design recommendations, Target architecture). The new `solution_implementation` holds the architecture description and the deployment guidance. The id `solution_architecture` was kept so recorded Executions and callers do not break. +2. The Ledger's existing rule does the gating: a Dependency across Phases is met only on Approval, so nothing in implementation is ready until design is approved. +3. The design Approval carries a summary of the graph (counts of Elements, Relationships and Checks, and recommendations treated as not applicable). `describe_prompt` in `app/presentation.py` states that no code is written until it is approved. +4. `workflow.yaml` lists the five Phases; its test checks it against the dependency graph. The A2A card derives from the graph and needed no change. + +Revision behaviour that follows: reopening the deployment guidance withdraws the implementation and validation Approvals and leaves the design approved; reopening the Target architecture withdraws design, implementation and validation, and the code cannot restart until the design is approved again. + +Tests: `tests/execution/test_ledger.py`, `test_the_user_approves_the_graph_before_any_code_is_written` in `tests/execution/test_requirements_chain.py`, `tests/execution/test_presentation.py`. diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-7.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-7.md new file mode 100644 index 0000000..3dc6774 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-7.md @@ -0,0 +1,10 @@ +# Step 7 — Implementation Detail + +1. `render_mermaid` draws a left-to-right flowchart with every Element (name and product) and every Relationship (its kind) exactly once. Node ids are generated, and characters Mermaid reserves are stripped from labels, so any graph step 3 accepts renders. +2. `submit_deliverable` adds `architecture.mmd` to the Target architecture's attachments when it accepts the submission. No Specialist draws it. +3. Removed: the `architecture_diagram` Deliverable, `agents/diagrammer.md` and its bundle entries. +4. `/generate` keeps its `mermaid_diagram` key, now read from the Target architecture. The packager is told to embed that attachment unchanged. + +The local `mermaid_check` tool stays in the bundle; the evaluation still uses it. + +Tests: `tests/execution/test_requirements_chain.py`, "the diagram is a view of the graph". diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-8.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-8.md new file mode 100644 index 0000000..fa40285 --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-8.md @@ -0,0 +1,9 @@ +# Step 8 — Implementation Detail + +1. The deployment guidance depends on the Target architecture and requires `implementation.json`: for each Check, the attached file and resource address that satisfies it. +2. Refused: a Check not accounted for, an id that is not a Check, an entry naming a file that is not attached. +3. `agents/iac-author.md` now says to implement the Target architecture and nothing it does not ask for, and on a Revision to change only what the failed Checks need. + +Changed from the plan: the IaC author's context still carries every earlier Deliverable in full, prose recommendations included, because `inputs_of` is unchanged. Narrowing it to the graph is iteration 4 step 13. + +Tests: `test_deployment_guidance_must_account_for_every_check`. diff --git a/.agents/plans/iter-06-target-architecture-graph/steps/step-9.md b/.agents/plans/iter-06-target-architecture-graph/steps/step-9.md new file mode 100644 index 0000000..2d61aff --- /dev/null +++ b/.agents/plans/iter-06-target-architecture-graph/steps/step-9.md @@ -0,0 +1,12 @@ +# Step 9 — Implementation Detail + +1. The validation results require `verdicts.json` in place of `findings.json`: a `dry_run` result, one verdict per Check (`pass`, `fail` or `not_verifiable`) with evidence, and a separate list of `proposed_additions`. +2. Refused: a Check with no verdict, a Check with two, a verdict on something that is not a Check, a verdict without evidence, a missing dry-run result. +3. A proposed addition is never a failure. This is the rule that stops validation findings growing between passes: the validator cannot add to what the code is judged against. +4. `validation_outcome` in `app/workflows/chain.py` separates faults in the code (failed Checks) from gaps in the graph (not verifiable, proposed additions). Lesson candidates and the evaluation use it. + +Changed from the plan: the dry-run is its own `dry_run` entry, not a Check in the graph, so the Target architecture stays free of tooling concerns. + +`check_findings` and `FINDINGS_ATTACHMENT` from iteration 4 step 1 are gone. Lesson candidate types are now `failed_check`, `unverifiable_check` and `proposed_addition`. + +Tests: `tests/execution/test_requirements_chain.py`, "code and validation answer the graph"; `tests/execution/test_lessons.py`. diff --git a/.agents/plans/iter-07-change-requests/DETAIL.md b/.agents/plans/iter-07-change-requests/DETAIL.md new file mode 100644 index 0000000..fc3a1f5 --- /dev/null +++ b/.agents/plans/iter-07-change-requests/DETAIL.md @@ -0,0 +1,60 @@ +# Plan Detail + +Every step is built test-first with the fake runtime and ends with `pytest`, `ruff check .` and `mypy .` passing. + +## Step 1: Accept ADR-0006 and update the glossary + +- **Capability:** A recorded decision, and vocabulary that no longer contradicts it. +- **The four points the owner confirms:** a Change request is a new Execution and never modifies its Baseline; the Baseline is a completed Execution of the same Customer case; the output is complete, not a patch; a Change request may itself be a Baseline. +- **Where:** `docs/adr/0006-*.md` status; `CONTEXT.md` entries for Execution, Session and Customer case, plus new entries **Change request** and **Baseline**; the sentence "An Execution starts clean" in `docs/adr/0004-*.md`. +- **Acceptance criteria:** The ADR is `accepted` or amended with this plan updated to match. No glossary entry says an Execution can never start from another. + +## Step 2: Start an Execution against a Baseline + +- **Capability:** A caller names a Baseline and the new Execution begins with its Deliverables. +- **Where:** `ExecutionEngine.start(baseline=...)` in `app/agent.py`; `/generate` body and A2A message metadata (`app/main.py`, `app/a2a_server.py`); `app/states/execution_state.py` (a `baseline` entry holding the Baseline's id and Deliverables); `execution.json` records the Baseline; `intent/history.json` records it on the new statement, so the history shows the line of versions. +- **Design:** The Baseline is loaded from its files under the Customer case, through `execution.json`, so it works across restarts and does not need the Baseline's checkpoint. +- **Acceptance criteria:** Start is refused, before anything runs, when the Baseline does not exist, is not completed, or belongs to another Customer case. An Execution started without a Baseline behaves exactly as today. The Baseline's files are byte-identical after the Change request completes. + +## Step 3: Requirements revised with a change record + +- **Capability:** The user's high-level statement of change becomes a precise change to the requirements. +- **Where:** `agents/requirements-analyst.md`; the requirements contract in `app/workflows/deliverables.py`; `agents/partials/specialist-protocol.md` (a `baseline` entry in the context). +- **Design:** `requirements.json` keeps the id of every requirement that still holds and gives each requirement a `change` of unchanged, added, changed or removed, with the reason. New requirements take new ids; an id is never reused. +- **Acceptance criteria:** Submission is refused when a Baseline requirement is missing from the revised list without being marked removed, or when a changed requirement has no reason. In an interactive Execution the analyst confirms the change record with the user before submitting. + +## Step 4: Later Specialists revise from the Baseline + +- **Capability:** Each Deliverable changes only where the changed requirements reach. +- **Where:** `_specialist_input` in `app/nodes/execution_nodes.py` (each Specialist receives the Baseline's version of its own Deliverable and the ids that changed upstream); every Specialist role file; the Target architecture Skill from iteration 6 step 4; `app/workflows/target_architecture.py` (a function that compares two graphs). +- **Design:** Ids are stable across versions: an Element, Relationship or Check that is unchanged keeps its id and its text. The engine computes what is reached by walking the Requirements chain from each changed requirement. +- **Acceptance criteria:** A test with the fake runtime shows that an Element or Check not reached by any changed requirement is identical to the Baseline's, and one that differs without being reached is reported in the change summary as an unrequested change. Validation still gives a verdict for every Check. + +## Step 5: Approvals show the change + +- **Capability:** The user approves what changed, not the whole architecture again. +- **Where:** `request_approval` in `app/tools/execution.py`, `app/presentation.py`, `agents/orchestrator.md`. +- **Acceptance criteria:** In a Change request, each Approval prompt lists what was added, changed and removed against the Baseline for that Phase's Deliverables, computed by the engine from the ids, not written by the Orchestrator. + +## Step 6: Change summary and version line in the case + +- **Capability:** A reader of a Customer case can see each version and what moved between them. +- **Where:** `_write_outputs` in `app/nodes/execution_nodes.py`; the packager role file. +- **Design:** Each Change request writes `changes.json` (requirements, Elements, Relationships and Checks added, changed and removed, each with its reason) and a readable summary in the solution guide. `intent/history.json` lists each statement with its Baseline. +- **Acceptance criteria:** The full Deliverables are written as for any Execution. `changes.json` matches a comparison of the two Executions' data files. Unrequested changes are listed separately from requested ones. + +## Step 7: Evaluation: a change case + +- **Capability:** Evidence that a change stays contained. +- **Where:** `eval/datasets/solution_cases.json`, `eval/solution_eval.py`, `eval/scoring.py`. +- **Design:** A case that runs a base request and then a Change request against it, for example retention moving from 30 days to 7 years. +- **Acceptance criteria:** The change case scores at least 0.8. New checks pass: every changed requirement reaches a changed or new Check; nothing outside its reach changed without being reported; the Change request used fewer tokens than its Baseline. + +## Step 8: Remove the `legacy-baseline` case + +- **Capability:** `deliverables/` holds only what the current engine produced. +- **Rationale:** `deliverables/cases/legacy-baseline/` is the output of the deleted iteration 1 pipeline: 68 Executions (62 of them from its tests and old benchmark) and its last shared copies in `as-is/`, `target/`, `validation/` and `guides/`. The owner chose on 2026-10-06 to keep it until this work is complete with the expected outcome, and to remove it then. +- **Gate:** Do this only when iteration 6 step 11 and step 7 here have both met their acceptance criteria. If either falls short, leave the case in place and say so. +- **Where:** `deliverables/cases/legacy-baseline/`; `scripts/validate_artifacts.py`, `tests/test_artifacts.py` and `tests/test_package.py`, which read its `as-is/`, `target/`, `validation/` and `guides/` folders and must be removed or pointed at a current Execution; `scripts/validate.sh`; `VALIDATION.md` step 1; the root `terraform/`, `docs/requirements.md`, `docs/architecture.md`, `docs/source-architecture.md` and `requirements.yaml`, which are the same pipeline's samples. +- **Guardrail:** Commit first, then delete in a commit of its own, so the removal can be reverted. +- **Acceptance criteria:** The case and the samples are gone, nothing in `scripts/` or `tests/` refers to them, and `pytest`, `ruff check .` and `mypy .` pass. diff --git a/.agents/plans/iter-07-change-requests/MAP.md b/.agents/plans/iter-07-change-requests/MAP.md new file mode 100644 index 0000000..d412a96 --- /dev/null +++ b/.agents/plans/iter-07-change-requests/MAP.md @@ -0,0 +1,37 @@ +# Plan Map + +**Iteration:** 7, Change requests +**Intent:** Let a user restate a request to say how their requirements have changed, at a high level, and receive the delivered architecture updated from where it stood, with an account of what changed and why. +**Status:** planned. ADR-0006 was accepted on 2026-10-07 and the glossary updated (step 1). Build after iteration 6 step 11 has a passing evaluation run +**This directory covers:** steps 1 to 8 + +## Sources of truth + +- `docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md`: the decision and its four points to confirm. Status `proposed`. +- `docs/adr/0005-the-target-architecture-is-an-explicit-graph.md` and `../iter-06-target-architecture-graph/`: the ids along the Requirements chain that a change is traced through. Build iteration 6 first. +- `CONTEXT.md`: today it says an Execution starts clean and a Customer case never feeds one Execution into another. Step 1 changes those entries; until then they stand. +- `iter-04-learning-and-skills/steps/step-15.md`: the Customer case layout, `execution.json` and the Intent history (`intent/history.json`) that a Baseline is found through. A Change request is the next statement in that history. + +## Status + +| Step | What | Size | Status | +|---|---|---|---| +| 1 | Accept ADR-0006 and update the glossary | S | complete: accepted 2026-10-07 | +| 2 | Start an Execution against a Baseline | M | planned | +| 3 | Requirements revised with a change record | M | planned | +| 4 | Later Specialists revise from the Baseline | M | planned | +| 5 | Approvals show the change | S | planned | +| 6 | Change summary and version line in the case | S | planned | +| 7 | Evaluation: a change case | M | planned | +| 8 | Remove the `legacy-baseline` case | S | complete: removed early on the owner's instruction, 2026-10-07 | + +## Dependency graph + +- Step 1: no dependencies +- Step 2: depends on step 1, iteration 4 step 15 +- Step 3: depends on step 2, iteration 6 step 2 +- Step 4: depends on step 3, iteration 6 steps 4 and 8 +- Step 5: depends on step 4, iteration 6 step 6 +- Step 6: depends on step 4 +- Step 7: depends on step 5, step 6, iteration 6 step 11 +- Step 8: no longer gated; done on 2026-10-07 diff --git a/.agents/plans/iter-07-change-requests/steps/step-8.md b/.agents/plans/iter-07-change-requests/steps/step-8.md new file mode 100644 index 0000000..9b0e9f5 --- /dev/null +++ b/.agents/plans/iter-07-change-requests/steps/step-8.md @@ -0,0 +1,13 @@ +# Step 8 — Implementation Detail + +Done early, on the owner's instruction of 2026-10-07 ("please remove legacy-baseline"). That instruction replaced the gate in `DETAIL.md`, which had held removal until iterations 6 and 7 met their acceptance criteria. Neither has: no evaluation run has been made on iteration 6, and iteration 7 is not built. + +1. Deleted `deliverables/cases/legacy-baseline/`: the 68 old Executions, their `intent/` history, and the shared `as-is/`, `target/`, `validation/` and `guides/` folders. `deliverables/cases/` is now empty until an Execution completes. +2. Deleted `scripts/validate_artifacts.py` and `tests/test_artifacts.py`, which only checked that case's samples. `tests/test_package.py` keeps its one test of `terraform/terraform.tfvars.example`. +3. Removed the artefact-validation step from `README.md` and `VALIDATION.md`. + +Five of the Execution folders were owned by a rootless-podman user id (110000), left by a container run on 2026-09-02 with the folder mounted. They were removed with `podman unshare rm`. + +Not committed first, against the guardrail in `DETAIL.md`: the owner did not ask for a commit. The tracked files are recoverable from commit `7ee49ab` at their earlier paths (`deliverables/as-is/`, `deliverables/target/`, `deliverables/validation/`, `deliverables/guides/`, `deliverables/executions/`, `scripts/validate_artifacts.py`, `tests/test_artifacts.py`). The generated `intent/` files for that case were never committed and are gone. + +Left in place, because the instruction named only `legacy-baseline`: the same pipeline's other samples, `terraform/` at the repository root, `docs/requirements.md`, `docs/architecture.md`, `docs/source-architecture.md`, `docs/validation-evidence.md`, `docs/validation-results.json`, `docs/publication-verification.md`, `requirements.yaml`, and `scripts/validate.sh`, which runs Terraform checks on that root `terraform/`. diff --git a/.dockerignore b/.dockerignore index 9648f75..d834a1c 100644 --- a/.dockerignore +++ b/.dockerignore @@ -8,4 +8,5 @@ *.db .env eval/results -deliverables/executions +deliverables/cases +lessons/candidates diff --git a/.env.example b/.env.example index 662abb6..abfa46c 100644 --- a/.env.example +++ b/.env.example @@ -29,13 +29,16 @@ MCP_TIMEOUT_SECONDS=30 # Local Terraform tools (fmt, validate, plan; never apply) TERRAFORM_BINARY=terraform TERRAFORM_TIMEOUT_SECONDS=300 -# TF_PLUGIN_CACHE_DIR=/var/cache/terraform-plugins +# Terraform providers are cached here so each check does not download them again. +# Relative to the repository root; set it empty to disable. +TF_PLUGIN_CACHE_DIR=.cache/terraform-plugins # Hierarchical Execution Engine ORCHESTRATOR_BUDGET=40 SPECIALIST_BUDGET=15 MAX_REVISIONS=3 MAX_ORCHESTRATOR_TURNS=100 +MAX_PARALLEL_SPECIALISTS=4 CHECKPOINTER=sqlite CHECKPOINT_DB_PATH=checkpoints.db diff --git a/.gitignore b/.gitignore index 2c8d8d0..f2da896 100644 --- a/.gitignore +++ b/.gitignore @@ -29,3 +29,6 @@ tfplan # Evaluation run outputs eval/results/ + +# Lesson candidates captured from Executions (may quote user feedback) +lessons/candidates/ diff --git a/.scratch/solution-architect-agent/spec.md b/.scratch/solution-architect-agent/spec.md index bf743b0..a4dfa14 100644 --- a/.scratch/solution-architect-agent/spec.md +++ b/.scratch/solution-architect-agent/spec.md @@ -121,6 +121,8 @@ scripts/sync-vendored-skills.sh `app/workflows/deliverables.py` declares the graph as data. It is the only place Phases, Deliverables and Dependencies are listed. +> **Changed on 2026-10-07 by [ADR-0005](../../docs/adr/0005-the-target-architecture-is-an-explicit-graph.md).** The table below is the graph as first built. The code now has five Phases, a `target_architecture` Deliverable between the design recommendations and the code, no `architecture_diagram` Deliverable (the diagram is rendered from the graph), and data files carrying ids along the Requirements chain (`app/workflows/chain.py`, `app/workflows/target_architecture.py`). See `.agents/plans/iter-06-target-architecture-graph/`. + | Phase | Deliverable kind | Specialist role | Depends on | Tools (tier) | |---|---|---|---|---| | 1 `requirements_discovery` | `requirements` | `requirements-analyst` | (none) | discovery MCP servers (cloud_read) | diff --git a/CONTEXT.md b/CONTEXT.md index ab36c37..8a9632b 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -11,15 +11,31 @@ The free-text description of the workload a caller wants architected; the openin _Avoid_: prompt, query, request summary **Execution**: -One solution-architecture engagement for a single Workflow request. It lasts from the first request to an approved Solution guide, and may span many user turns. +One solution-architecture engagement for a single Workflow request. It lasts from the first request to an approved Solution guide, and may span many user turns. An Execution starts clean, unless it is a Change request. _Avoid_: run, job, workflow execution **Session**: -A caller-supplied grouping of Executions. A Session never feeds earlier outputs into a later Execution; each Execution starts clean. +A caller-supplied grouping of Executions. A Session never feeds earlier outputs into a later Execution. _Avoid_: conversation, context +**Customer case**: +A caller-supplied grouping of the Executions run for one customer workload, identified by a short slug. Every Execution belongs to one; an Execution started without one belongs to `unassigned`. A Customer case ties each request to the Deliverables generated for it. It feeds one Execution's outputs into another only when the caller starts a Change request and names the Baseline. +_Avoid_: engagement, project, account, tenant + +**Intent**: +What the customer wants from a Customer case, in their own words and at a high level. Each Workflow request made in the case is a statement of it, and the statements are kept in order as its history. The Intent is the customer's; requirements are what the agents derive from it. +_Avoid_: brief, ask, requirements (which are the derived Deliverable) + +**Change request**: +An Execution started to say how the customer's Intent has changed. It begins from a Baseline and delivers the full updated Deliverables with an account of what changed and why. +_Avoid_: amendment, update run, iteration, re-run + +**Baseline**: +The completed Execution, in the same Customer case, that a Change request starts from. A Baseline is never modified. +_Avoid_: parent, previous run, source Execution + **Phase**: -A named grouping of Deliverables: requirements discovery, solution architecture, solution validation, or packaging. A Phase is complete when all its Deliverables are submitted and the user has granted the Phase's Approval. +A named grouping of Deliverables: requirements discovery, solution architecture (the design, ending with the Target architecture), solution implementation, solution validation, or packaging. A Phase is complete when all its Deliverables are submitted and the user has granted the Phase's Approval. _Avoid_: step, node, stage, pipeline **Approval**: @@ -37,7 +53,7 @@ The top-level agent of an Execution, and the only agent that talks to the user. _Avoid_: supervisor, manager, root agent, router **Specialist**: -An agent responsible for producing one kind of Deliverable, such as the product selector or the diagrammer. A Specialist may delegate independent parts of its work to further Specialists. +An agent responsible for producing one kind of Deliverable, such as the product selector or the target architect. A Specialist may delegate independent parts of its work to further Specialists. _Avoid_: sub-agent, worker, phase agent, node ### Portability @@ -53,13 +69,33 @@ _Avoid_: hyperscaler, cloud, platform, target ### Outputs **Deliverable**: -A document an Execution produces: requirements, technical decomposition, product selection, architecture diagram, architecture description, design recommendations, deployment guidance, validation results, or the Solution guide. Each Deliverable depends on others being approved first. +A document an Execution produces: requirements, technical decomposition, product selection, design recommendations, the Target architecture, architecture description, deployment guidance, validation results, or the Solution guide. Each Deliverable depends on others being approved first. _Avoid_: artifact, output file **Dependency**: The relationship between two Deliverables in which one can only be produced once the other has been accepted, for example an architecture diagram depending on the product selection. Within a Phase, a submitted Deliverable counts as accepted. Across Phases, only the earlier Phase's Approval does. _Avoid_: prerequisite, edge, upstream +**Target architecture**: +The solution to be built, as one explicit graph of Elements, the Relationships between them, and the Checks each must meet. It is established before any infrastructure code is written, and every later Deliverable is derived from it and checked against it. +_Avoid_: build plan, blueprint, design doc, to-be state + +**Element**: +One component of the Target architecture and the cloud resource that realises it, with the product selected for it. +_Avoid_: node, resource (alone), box + +**Relationship**: +A connection between two Elements, such as calls, publishes to, reads from, or is granted access to. +_Avoid_: edge, link, dependency (which is between Deliverables) + +**Check**: +A numbered, verifiable condition that an Element or Relationship must meet, traced to the requirement or design recommendation it comes from. Validation gives each Check a verdict. +_Avoid_: finding, rule, control, test + +**Requirements chain**: +The unbroken trace from each requirement, through the components that serve it and the Elements and Checks that realise it, to the code that implements them and the validation verdict on each Check. +_Avoid_: traceability matrix, lineage + **Solution guide**: The packaged Deliverable that assembles every other Deliverable into the Cloud provider's solution architecture template. _Avoid_: final report, package diff --git a/README.md b/README.md index 325da4d..aa632a5 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,15 @@ Vocabulary is defined in [CONTEXT.md](CONTEXT.md), decisions in [docs/adr/](docs ### 1. Orchestrator and Specialists (`agents/`) One Orchestrator coordinates an Execution and is the only agent that talks to the user. It delegates each Deliverable to one Specialist, and independent Deliverables run in parallel: - **Requirements discovery:** `requirements-analyst`, `decomposer`. -- **Solution architecture:** `product-selector`, `diagrammer`, `describer`, `design-advisor` (which consults one `pillar-advisor` per architecture-framework pillar), `iac-author`. +- **Solution architecture (design):** `product-selector`, `design-advisor` (which consults one `pillar-advisor` per architecture-framework pillar), `target-architect`. +- **Solution implementation:** `describer`, `iac-author`. - **Solution validation:** `validator`. - **Packaging:** `packager`. Each Phase needs the user's explicit Approval before work that depends on it starts. A pre-approved mode serves batch and evaluation runs. +The design Phase ends with the **Target architecture**: one explicit graph of Elements, Relationships and Checks ([ADR-0005](docs/adr/0005-the-target-architecture-is-an-explicit-graph.md)). The user approves it before any infrastructure code is written. The diagram is drawn from it by code, the Terraform must account for every Check, and validation gives a verdict per Check. Requirements, components, products and recommendations each carry ids in a data file, so every requirement can be traced through to its verdict; a submission with a missing link is refused. + ### 2. LangGraph state, ADK agents (`app/`) Per [ADR-0003](docs/adr/0003-langgraph-holds-state-adk-agents-reason.md): - A LangGraph `StateGraph` holds the Execution: the dependency graph of Deliverables (`app/workflows/deliverables.py`), the Ledger of their states (`app/states/ledger.py`), checkpoints, and `interrupt()` whenever the user must answer or approve. @@ -38,7 +41,7 @@ The container starts the hierarchical Execution engine (ADR-0003) behind an A2A - `POST /a2a`: A2A JSON-RPC for interactive, multi-turn Executions with Approvals. - `GET /.well-known/agent-card.json`: A2A agent card. - `GET /health`: Health signal, the Cloud provider and any MCP discovery gaps. -- `POST /generate`: One-shot, pre-approved Execution for batch and evaluation callers. +- `POST /generate`: One-shot, pre-approved Execution for batch and evaluation callers. Pass `customer_case` to group it with the case's other Executions; over A2A, send `customer_case` in the message metadata. The original linear pipeline and its REST routes (`/card`, `/validate`, `/sessions/{session_id}`) were removed on 2026-10-06; see `.agents/plans/iter-03-kab-layout/`. @@ -59,9 +62,6 @@ pytest -q # Real-model evaluation of the engine (costs model usage; see eval/solution_eval.py) python3 -m eval.solution_eval - -# Run static artifact validation -python3 scripts/validate_artifacts.py ``` ### Start the A2A Server @@ -77,7 +77,7 @@ podman build -t gcp-solution-architecture-agent:latest . ``` #### 2. Run Container with Host Deliverables Volume Mount -To ensure execution deliverables (`deliverables/executions/{execution_id}/*`) are written directly to your host machine's workspace: +To ensure Execution outputs (`deliverables/cases/{customer_case}/executions/{execution_id}/*`) are written directly to your host machine's workspace: ```bash podman run -d --name gcp-agent \ @@ -115,7 +115,7 @@ curl http://localhost:8080/.well-known/agent-card.json # Run a pre-approved Execution curl -X POST http://localhost:8080/generate \ -H "Content-Type: application/json" \ - -d '{"request": "Event-driven regional HTTP application in Podman"}' + -d '{"request": "Event-driven regional HTTP application in Podman", "customer_case": "acme-webhooks"}' ``` --- @@ -147,23 +147,25 @@ gcp_solution_architecture_agent/ │ ├── solution_eval.py # Real-model evaluation of the Execution engine │ ├── scoring.py # Checks applied to a finished Execution │ └── datasets/ # Benchmark cases (JSON) -├── deliverables/ # Scalable deliverable repository (categorized & versioned) -│ ├── as-is/ # Pre-emptive Source Environment Deliverables (Before State) -│ │ ├── source-architecture.md -│ │ └── source-architecture.mmd -│ ├── target/ # Target Architecture Deliverables (After State) -│ │ ├── requirements.md -│ │ ├── architecture.md -│ │ └── architecture.mmd -│ ├── validation/ # Pre-deployment Validation Reports -│ │ └── validation-results.md -│ ├── guides/ # Consolidate Solution Architecture Guides -│ │ └── solution-architecture-guide.md -│ └── executions/ # Per-Execution Versioned Snapshots ({execution_id}/*) +├── deliverables/ +│ └── cases/ # Everything generated, grouped by Customer case +│ └── / +│ ├── intent/ # What the customer asked for, and how it has changed +│ │ ├── 001.md, 002.md # Each request as the customer stated it, in order +│ │ └── history.json # Every request, the Execution it started and how it ended +│ └── executions// +│ ├── execution.json # Request, status and files of this Execution +│ ├── solution-architecture-guide.md +│ ├── deliverables/.md # One per Deliverable +│ ├── requirements.json, components.json, products.json, recommendations.json +│ ├── target-architecture.json # Elements, Relationships and Checks +│ ├── architecture.mmd # Drawn from the graph +│ ├── terraform/, implementation.json # The code, and which part meets each Check +│ └── verdicts.json # Validation's verdict on each Check +├── lessons/candidates// # Lesson candidates per Execution (gitignored) ├── docs/ # Specifications, audit notes & verification records ├── terraform/ # Deployable GCP Terraform IaC blueprint -├── scripts/ -│ └── validate_artifacts.py # Static artifact validation script +├── scripts/ # Vendored-Skill sync, MCP tool listing, Terraform checks └── tests/ # Unit & integration test suite ``` diff --git a/VALIDATION.md b/VALIDATION.md index b4f6335..f7b5234 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -3,19 +3,22 @@ Run from the repository root without credentials: ```bash -# 1. Static artifact & guide section validation -python3 scripts/validate_artifacts.py - -# 2. Pytest unit & integration test suite +# 1. Pytest unit & integration test suite pytest -v -# 3. Real-model evaluation of the engine (needs model credentials; costs usage) +# 2. Real-model evaluation of the engine (needs model credentials; costs usage) python3 -m eval.solution_eval -# 4. Optional Terraform formatting & validation +# 3. Optional Terraform formatting & validation terraform -chdir=terraform fmt -check -recursive terraform -chdir=terraform init -backend=false terraform -chdir=terraform validate ``` `init -backend=false` may download the pinned provider constraint but does not create infrastructure. Do not use `terraform apply` as part of validation. A deployment candidate additionally requires an operator-supplied `terraform plan -out=tfplan` and human review. + +## Evaluation options + +- `python3 -m eval.solution_eval --judge` adds the judged checks: coverage of each pillar Skill's validation checklist, and a quality rubric for the design recommendations. +- `python3 -m eval.solution_eval case-04-interactive-web-app` runs one case with a scripted user in the loop. +- A case's `thresholds` in `eval/datasets/solution_cases.json` bound its revisions, seconds and tokens; exceeding one is reported as a regression. diff --git a/agents/decomposer.md b/agents/decomposer.md index 5c1c904..7eb0bd8 100644 --- a/agents/decomposer.md +++ b/agents/decomposer.md @@ -8,4 +8,5 @@ You produce the **technical decomposition** Deliverable: the Skill's breakdown o - Derive every component from the approved requirements, and name the requirements each component serves. - Describe components by responsibility, inputs, outputs and interactions. +- Give every component an id and attach them as `components.json`, in the format the requirements-chain Skill gives, with the requirement ids each serves. Every functional requirement must be served by a component. - Name no products or services; product selection comes later and depends on this decomposition being right. diff --git a/agents/describer.md b/agents/describer.md index 1cd9d91..0b42091 100644 --- a/agents/describer.md +++ b/agents/describer.md @@ -6,6 +6,6 @@ includes: [specialist-protocol] --- You produce the **architecture description** Deliverable: the Skill's task for describing the architecture. -- Explain the purpose of each component in the diagram, the relationships between components, and the task flow or data flow end to end. -- Use the product names from the product selection and the component names from the diagram exactly. +- Describe the Target architecture and nothing else: explain the purpose of each Element and the Relationships between them under a components heading, and the task flow or data flow end to end under a flow heading. +- Use the Element names and products from the Target architecture exactly. - Ground claims about product behaviour in the Cloud provider's documentation through your documentation tools, with citations. diff --git a/agents/design-advisor.md b/agents/design-advisor.md index 53b5ac2..212ce17 100644 --- a/agents/design-advisor.md +++ b/agents/design-advisor.md @@ -7,7 +7,9 @@ includes: [specialist-protocol] You produce the **design recommendations** Deliverable: the Skill's task for recommending how to configure each component to meet the functional and non-functional requirements. - Call `consult_pillar_advisors` once, with a brief that restates the workload, the relevant requirements and the selected products. It runs one advisor per architecture-framework pillar in parallel and returns their guidance. +- When `feedback` is not empty you are revising: pass `pillars` naming only the pillars the feedback touches. The guidance you were given before is returned for the others. - Reconcile the pillars' guidance into recommendations for each component. Where pillars conflict, name the trade-off and recommend a resolution tied to the requirements. - When an advisor's guidance is missing, derive that pillar's recommendations from the best-practices references in the solution-architecture Skill. +- Give every recommendation an id and attach them as `recommendations.json`, in the format the requirements-chain Skill gives. Write one configurable decision per recommendation, so each can become a Check in the Target architecture. -Required headings, one per pillar: `Security, privacy, and compliance`, `Reliability`, `Operational excellence`, `Cost optimization`, `Performance efficiency`, `Sustainability`. +Your contract's sections are one per pillar. diff --git a/agents/diagrammer.md b/agents/diagrammer.md deleted file mode 100644 index fbd91c5..0000000 --- a/agents/diagrammer.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -role: diagrammer -deliverable: architecture_diagram -tools: [mermaid_check] -includes: [specialist-protocol] ---- -You produce the **architecture diagram** Deliverable: the Skill's task for generating a Mermaid architecture diagram. - -- Draw every component from the product selection and every relationship the data and control flow need, labelled with the selected products. -- Check the diagram with your Mermaid tool when one is available, and fix every error it reports. -- Put the diagram source in the `architecture.mmd` attachment, and show the same diagram in a `mermaid` code block in the content with a one-paragraph legend. diff --git a/agents/iac-author.md b/agents/iac-author.md index cce636f..8f62d6c 100644 --- a/agents/iac-author.md +++ b/agents/iac-author.md @@ -7,10 +7,12 @@ includes: [specialist-protocol] --- You produce the **deployment guidance** Deliverable: the Skill's task for generating infrastructure-as-code and deployment instructions. -- Write Terraform that provisions every selected product with the configuration the design recommendations call for. +- Write Terraform that implements the Target architecture: every Element, every Relationship and every Check, and nothing it does not ask for. +- Attach `implementation.json`, in the format the requirements-chain Skill gives, naming where the code satisfies each Check. - Take every environment-specific value (project, region, names, image references) from variables; embed no credentials or secrets. - Format and validate the Terraform with your tools when they are available, and fix everything they report. Pass the files with the same `terraform/` paths you will attach. - Submit as soon as validation passes. If a submission is refused, fix exactly what the refusal lists and submit again; don't rewrite the Terraform. -- Put `terraform/main.tf` and `terraform/variables.tf` in the attachments (a list of `{path, content}`), adding `terraform/outputs.tf` when outputs help. +- Put `terraform/main.tf`, `terraform/variables.tf` and `implementation.json` in the attachments (a list of `{path, content}`), adding `terraform/outputs.tf` when outputs help. +- When `feedback` lists failed Checks, change only what those Checks need. -Required headings: `Deployment prerequisites` (APIs to enable, tools, permissions) and `Step-by-step deployment instructions`, whose commands you give for the user to run, never run yourself. +Under the prerequisites heading, list the APIs to enable, the tools and the permissions. Under the instructions heading, give commands for the user to run; never run them yourself. diff --git a/agents/orchestrator.md b/agents/orchestrator.md index e32cd8c..276b5d2 100644 --- a/agents/orchestrator.md +++ b/agents/orchestrator.md @@ -6,15 +6,17 @@ You coordinate one solution-architecture Execution for the user. You decide what Load the solution-architecture Skill available to you for the workflow's rules: strict separation between requirements discovery and solutioning, explicit user approval of each Phase, and no execution of generated scripts. -Your task message carries JSON context: `workflow_request`, each Deliverable's `status`, `revisions` and `feedback`, each Phase's status, `ready_work`, `phases_ready_for_approval`, `pending_questions` from Specialists, the recent `conversation`, `notes` about discarded results, `pre_approved` and `allow_cloud_read`. +Your task message carries JSON context: `workflow_request`, each Deliverable's `status`, `revisions` and `feedback`, each Phase's status, `ready_work`, `phases_ready_for_approval`, `validation` (the verdict on each Check, once validation is submitted), `pending_questions` from Specialists, the recent `conversation`, `notes` about discarded results, `pre_approved` and `allow_cloud_read`. On each turn, take the first step that applies: 1. **The user asked for changes.** When the latest user message in `conversation` asks to change submitted work, call `reopen` for each affected Deliverable with the user's words as the reason. 2. **Specialists are waiting.** When `pending_questions` is not empty, call `ask_user`. Add your own questions only when the user's last message left something unclear. -3. **A Phase is complete.** When `phases_ready_for_approval` names a Phase, read its Deliverables with `read_deliverable` and call `request_approval` with a summary a busy architect can approve from. In a pre-approved Execution the approval is granted immediately, and you continue with the next step in the same turn. -4. **Work is ready.** When `ready_work` is not empty, call `delegate` once with every ready Deliverable, so independent work runs in parallel. -5. **Validation found problems.** When the validation results report failures that trace to an earlier Deliverable, call `reopen` on that Deliverable with the findings, then delegate it. +3. **Validation decided.** When `validation` is set and the validation Phase is not yet approved, act on it before asking for Approval: + - `failed` is not empty, or `dry_run.verdict` is `fail`: the code is at fault. Call `reopen` on `deployment_guidance`, giving each failed Check's id and evidence as the reason, then delegate it. + - otherwise `not_verifiable` or `proposed_additions` is not empty: the Target architecture has a gap. When `pre_approved` is `false`, call `ask_user` to ask whether to revise the Target architecture, listing each item. When `pre_approved` is `true`, call `reopen` on `target_architecture` for the items whose reason names a requirement or recommendation id, then delegate it; ignore the rest. +4. **A Phase is complete.** When `phases_ready_for_approval` names a Phase, read its Deliverables with `read_deliverable` and call `request_approval` with a summary a busy architect can approve from. In a pre-approved Execution the approval is granted immediately, and you continue with the next step in the same turn. +5. **Work is ready.** When `ready_work` is not empty, call `delegate` once with every ready Deliverable, so independent work runs in parallel. 6. **Packaging is approved.** Call `finish`. 7. **Otherwise,** call `ask_user` to find out what the user needs. diff --git a/agents/packager.md b/agents/packager.md index 79948b5..c6918e4 100644 --- a/agents/packager.md +++ b/agents/packager.md @@ -8,6 +8,7 @@ You produce the **solution guide** Deliverable: the Skill's packaging of every a - Load the solution-guide output template from the Skill's assets and follow its structure and section numbering exactly. - Consolidate the content of every Deliverable in `dependencies`; rewrite for flow, but keep every requirement, product decision, citation, recommendation, command and validation verdict. -- Include the architecture diagram as a `mermaid` code block and the Terraform as code blocks. +- Include the architecture diagram, which is the `architecture.mmd` attachment of the Target architecture, unchanged as a `mermaid` code block, and the Terraform as code blocks. +- List the Target architecture's Checks with their validation verdicts in the validation section. -Required headings: the template's eight top-level sections. +Your contract's sections are the template's eight top-level sections. diff --git a/agents/partials/specialist-protocol.md b/agents/partials/specialist-protocol.md index 53cd261..b747db5 100644 --- a/agents/partials/specialist-protocol.md +++ b/agents/partials/specialist-protocol.md @@ -8,13 +8,15 @@ Your task message carries JSON context: - `dependencies`: every earlier Deliverable your work builds on, by kind, with its `content` and `attachments`. - `feedback`: why earlier versions of your Deliverable were revised. Address every item. - `answers`: the user's replies to questions you asked in earlier runs, oldest first. +- `contract`: what `submit_deliverable` checks. `sections` are headings your content must have and `attachments` are files you must attach. A data file among them must also keep every id traceable to the Deliverables in `dependencies`; the requirements-chain Skill gives each file's format. +- `draft`: the draft you sent the user with your last questions, with its `attachments`, or `null`. - `pre_approved`: `true` when no user is available. Steps: 1. Load the Skill available to you and find the part that covers your Deliverable. Read the references and assets it points to with `load_skill_resource`. 2. Ground your work in `dependencies`, `feedback` and `answers`. When you need information only the user has, call `needs_input` with all your questions at once, each saying why it matters. Your run ends there, and you are started again with the answers. -3. Draft the Deliverable. When `pre_approved` is `false`, confirm the draft with the user before submitting: call `needs_input` with a short summary of the draft and ask them to approve it or request changes. Skip this when `answers` already holds their approval of the same draft. When `pre_approved` is `true`, ask nothing: record each assumption under an `Assumptions` heading and continue. -4. Call `submit_deliverable` with the complete markdown content and every required attachment. When it reports missing sections or attachments, add them and submit again. +3. Draft the Deliverable to its `contract`. When `pre_approved` is `false`, confirm the draft with the user before submitting: call `needs_input` with a short summary of the draft, asking them to approve it or request changes, and pass the complete draft as `draft` with its `attachments`. When `draft` is set and the latest entry in `answers` approves it, submit that draft as it is; when the user asked for changes, apply them to that draft. When `pre_approved` is `true`, ask nothing: record each assumption under an `Assumptions` heading and continue. +4. Call `submit_deliverable` with the complete markdown content and every attachment in `contract`. When it reports what is missing, add it and submit again. You are done when `submit_deliverable` accepts the Deliverable. diff --git a/agents/product-selector.md b/agents/product-selector.md index 2549285..c71e37a 100644 --- a/agents/product-selector.md +++ b/agents/product-selector.md @@ -10,4 +10,6 @@ You produce the **product selection** Deliverable: the Skill's task for identify - Check the release status of every product you recommend, and recommend nothing deprecated, retired or unsupported. - Where alternatives exist, follow the documentation's guidance on choosing, and list the alternatives with their pros and cons. -Required heading: `Products and features mapping`, containing a table with columns for component, recommended product or feature, justification and citations, alternatives, and their pros and cons. +Attach `products.json`, in the format the requirements-chain Skill gives, with the one product selected for each component. + +Under the products mapping heading, give a table with columns for component, recommended product or feature, justification and citations, alternatives, and their pros and cons. diff --git a/agents/requirements-analyst.md b/agents/requirements-analyst.md index cf4198b..5eabe75 100644 --- a/agents/requirements-analyst.md +++ b/agents/requirements-analyst.md @@ -7,9 +7,11 @@ includes: [specialist-protocol] You produce the **requirements** Deliverable: the Skill's requirements-discovery gathering and its resolution of ambiguities and contradictions. - Cover functional requirements, non-functional requirements (security, privacy, compliance, reliability, disaster recovery, cost, operations, performance, sustainability), current state, and dependencies. -- When non-functional requirements are missing, ask for them and explain what each one decides: availability tiers, scaling, cost budgets, resource types and security posture. +- The user states what they want at a high level; the detail is your job. When a non-functional requirement is missing, propose a default for it from the Cloud provider's architecture framework and record it under `Assumptions` with what it decides: availability tiers, scaling, cost budgets, resource types and security posture. Ask the user to confirm the whole set in one question. +- Ask an open question only where no sensible default can be inferred from the request, such as the region, a compliance regime or a budget ceiling. - Name every ambiguity or contradiction, explain why the conflicting goals can't both hold, and ask the user to choose. When they delegate the choice, propose one and ask them to approve it. - When the user runs workloads in a cloud environment today, use your cloud discovery tools to describe the current state from what actually exists, and record anything you couldn't read as a discovery gap. - Name no products, services or architectures. This Deliverable describes the problem, not the solution. +- Give every requirement an id and attach them all as `requirements.json`, in the format the requirements-chain Skill gives. Use the same ids in your content. -Required headings: `Functional requirements`, `Non-functional requirements`, `Current state`, `Dependencies`. Add `Open questions` and `Assumptions` when they apply. +Add `Open questions` and `Assumptions` headings when they apply. diff --git a/agents/target-architect.md b/agents/target-architect.md new file mode 100644 index 0000000..2057f9b --- /dev/null +++ b/agents/target-architect.md @@ -0,0 +1,17 @@ +--- +role: target-architect +deliverable: target_architecture +tools: [] +includes: [specialist-protocol] +--- +You produce the **Target architecture** Deliverable: the solution as one explicit graph of Elements, Relationships and Checks. It is agreed before any infrastructure code is written, and the diagram, the description, the code and the validation are all derived from it. + +- Load the requirements-chain Skill for the graph's format and how to derive it. +- Give every component an Element with the product selected for it, and add the supporting Elements the design needs, such as identities, policies and networks. +- Give every connection between Elements a Relationship. +- Turn every non-functional requirement and every design recommendation into Checks on the Elements and Relationships they constrain. Write each Check so that it can be verified from infrastructure code alone, naming the setting and the value it must have. +- Decide the implementation detail yourself from the design recommendations and the Cloud provider's documentation, through your documentation tools. The user states intent at a high level; this level of detail is your job. +- When a recommendation does not apply to this workload, list it as not applicable with the reason. The user sees that list when they approve the design. +- Attach the graph as `target-architecture.json`. The diagram is drawn from it for you. + +Under each of your contract's sections, give the Elements, Relationships and Checks as tables a person can review. diff --git a/agents/validator.md b/agents/validator.md index a941f92..c22d149 100644 --- a/agents/validator.md +++ b/agents/validator.md @@ -7,8 +7,9 @@ includes: [specialist-protocol] You produce the **validation results** Deliverable: the Skill's pre-deployment validation, done statically without provisioning anything. - Run the deployment dry-run with your tools: format and validate the Terraform, and preview it with a plan when you have permission to read live cloud resources. -- Analyse the architecture and policy statically: network routing and exposure, firewall rules, and IAM least privilege, against the design recommendations. -- Report each finding with its evidence and the Deliverable it traces to, so the Orchestrator can send it back for revision. +- Give a verdict on every Check in the Target architecture, from the infrastructure code: pass, fail or not verifiable, each with the evidence you read. The Checks are the whole bar: judge the code against them and nothing else. +- When you see something the Target architecture lacks, record it as a proposed addition, naming the requirement or recommendation it serves. It is not a failure of the code. +- Attach the verdicts as `verdicts.json`, in the format the requirements-chain Skill gives. - Give the exact commands for every check you couldn't run, for the user to run themselves. -Required headings: `Deployment dry-run` and `Architecture and policy analysis`, each ending with a pass or fail verdict. +End each of your contract's sections with a pass or fail verdict. diff --git a/app/a2a_server.py b/app/a2a_server.py index e5a52fd..7dae199 100644 --- a/app/a2a_server.py +++ b/app/a2a_server.py @@ -56,6 +56,7 @@ class SolutionArchitectExecutor(AgentExecutor): interaction = await self._engine.start( context.get_user_input(), session_id=context.context_id, + customer_case=options.get("customer_case"), execution_id=task_id, pre_approved=bool(options.get("pre_approved", False)), allow_cloud_read=options.get("allow_cloud_read"), diff --git a/app/adk/adk_runtime.py b/app/adk/adk_runtime.py index 5fc0e68..87a1efb 100644 --- a/app/adk/adk_runtime.py +++ b/app/adk/adk_runtime.py @@ -31,6 +31,7 @@ from google.adk.tools.tool_context import ToolContext from google.genai import types from app.adk.runtime import ( + REJECTION_PREFIXES, AgentTask, BudgetExhausted, Outcome, @@ -52,13 +53,6 @@ TIMED_OUT = ( "Your last model request timed out, so its reply was lost. Continue the task, " "and finish by calling the tool your instructions name for ending your turn." ) -# Tool replies that mean the call did nothing, logged so stuck agents can be diagnosed. -REJECTION_PREFIXES = ( - "Not submitted", - "Refused", - "Discovery gap", - "terraform validate failed", -) # Client-side timeouts from either HTTP stack google-genai may use (httpx or aiohttp, # whose timeout errors subclass TimeoutError). MODEL_TIMEOUTS = (TimeoutError, httpx.TimeoutException) diff --git a/app/adk/fake_runtime.py b/app/adk/fake_runtime.py index 2221481..063f372 100644 --- a/app/adk/fake_runtime.py +++ b/app/adk/fake_runtime.py @@ -7,6 +7,7 @@ enforce is exercised exactly as a model would meet it. from __future__ import annotations +import json from collections import deque from collections.abc import Callable, Mapping, Sequence from dataclasses import dataclass, field @@ -20,6 +21,7 @@ from app.adk.runtime import ( Stopped, ToolSpec, ) +from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind @dataclass(frozen=True) @@ -31,6 +33,97 @@ class Call: Turn = Sequence[Call] | Callable[[AgentTask], Sequence[Call]] +# One small, coherent Requirements chain, so sample submissions pass every link. +SAMPLE_DATA: dict[str, str] = { + "requirements.json": json.dumps( + [ + {"id": "FR-1", "kind": "functional", "text": "Accept events."}, + {"id": "NFR-1", "kind": "non_functional", "text": "99.9% availability."}, + ] + ), + "components.json": json.dumps( + [{"id": "C-1", "name": "Ingress", "requirements": ["FR-1", "NFR-1"]}] + ), + "products.json": json.dumps([{"component": "C-1", "product": "Example Run"}]), + "recommendations.json": json.dumps( + [ + { + "id": "DR-1", + "pillar": "security", + "text": "Use a dedicated identity.", + "components": ["C-1"], + } + ] + ), + "target-architecture.json": json.dumps( + { + "elements": [ + { + "id": "E-1", + "name": "Ingress service", + "component": "C-1", + "product": "Example Run", + "resource_type": "example_run_service", + }, + { + "id": "E-2", + "name": "Ingress identity", + "product": "Example IAM", + "resource_type": "example_service_account", + }, + ], + "relationships": [ + {"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"} + ], + "checks": [ + { + "id": "K-1", + "applies_to": "E-1", + "statement": "The service runs at least two instances.", + "source": "NFR-1", + }, + { + "id": "K-2", + "applies_to": "E-2", + "statement": "The identity is used by this service only.", + "source": "DR-1", + }, + ], + } + ), + "implementation.json": json.dumps( + [ + {"check": "K-1", "file": "terraform/main.tf", "address": "example.run"}, + {"check": "K-2", "file": "terraform/main.tf", "address": "example.sa"}, + ] + ), + "verdicts.json": json.dumps( + { + "dry_run": {"verdict": "pass", "evidence": "terraform validate passed."}, + "checks": [ + {"check": "K-1", "verdict": "pass", "evidence": "min instances is 2."}, + {"check": "K-2", "verdict": "pass", "evidence": "One binding."}, + ], + "proposed_additions": [], + } + ), +} + + +def sample_submission(kind: DeliverableKind, note: str = "") -> Call: + """A `submit_deliverable` call that meets the Deliverable's contract.""" + spec = DEPENDENCY_GRAPH[kind] + parts = [f"# {kind}", note or "Summary."] + parts += [f"## {section}\n{note or 'Details.'}" for section in spec.sections] + attachments = { + name: SAMPLE_DATA.get(name, f"# {name}\n") for name in spec.attachments + } + return Call( + "submit_deliverable", + {"content": "\n".join(parts) + "\n", "attachments": attachments}, + ) + + @dataclass(frozen=True) class RunRecord: role: str diff --git a/app/adk/runtime.py b/app/adk/runtime.py index 605f22b..424bf12 100644 --- a/app/adk/runtime.py +++ b/app/adk/runtime.py @@ -6,7 +6,17 @@ a RoleSpec, an AgentTask and ToolSpecs in; an Outcome back. No framework types. from __future__ import annotations -from collections.abc import Awaitable, Callable, Mapping, Sequence +import asyncio +import contextvars +from collections.abc import ( + AsyncIterator, + Awaitable, + Callable, + Mapping, + MutableMapping, + Sequence, +) +from contextlib import asynccontextmanager from dataclasses import dataclass, field from typing import Any, Protocol @@ -47,10 +57,15 @@ class Submitted: @dataclass(frozen=True) class NeedsInput: - """The agent can't continue without the user. `permission` names a tool tier to grant.""" + """The agent can't continue without the user. `permission` names a tool tier to grant. + + `draft` is work the agent wants back when it is started again with the answers. + """ questions: tuple[str, ...] permission: str | None = None + draft: str | None = None + draft_attachments: Mapping[str, str] = field(default_factory=dict) @dataclass(frozen=True) @@ -127,8 +142,62 @@ class ToolSpec: tier: str = "general" # general | cloud_read | execution -# The tools a role gets beyond the Execution tools, given the Deliverable it is producing. -ToolFactory = Callable[[RoleSpec, str | None], Sequence[ToolSpec]] +# The tools a role gets beyond the Execution tools, given the Deliverable it is producing +# and that Deliverable's working memory: JSON-compatible data a tool may read and write, +# kept with the Execution across attempts. +ToolFactory = Callable[ + [RoleSpec, str | None, MutableMapping[str, Any]], Sequence[ToolSpec] +] + + +class RunLimiter: + """Caps how many agent runs are in flight at once. + + A run that fans out to further runs lends its slot while it waits, so the cap + holds across the whole hierarchy and a cap of 1 cannot deadlock. + """ + + def __init__(self, limit: int) -> None: + if limit < 1: + raise ValueError("limit must be at least 1") + self.limit = limit + self._semaphore = asyncio.Semaphore(limit) + self._holding: contextvars.ContextVar[bool] = contextvars.ContextVar( + "run_limiter_holding", default=False + ) + + @asynccontextmanager + async def slot(self) -> AsyncIterator[None]: + async with self._semaphore: + token = self._holding.set(True) + try: + yield + finally: + self._holding.reset(token) + + @asynccontextmanager + async def lend(self) -> AsyncIterator[None]: + """Give up the caller's slot, if it holds one, while its own fan-out runs.""" + if not self._holding.get(): + yield + return + self._semaphore.release() + token = self._holding.set(False) + try: + yield + finally: + self._holding.reset(token) + await self._semaphore.acquire() + + +# Tool replies that mean the call did nothing. Runtimes log them, and the Execution +# keeps them as lesson candidates. +REJECTION_PREFIXES = ( + "Not submitted", + "Refused", + "Discovery gap", + "terraform validate failed", +) class AgentRuntime(Protocol): diff --git a/app/agent.py b/app/agent.py index ad9dc55..e154880 100644 --- a/app/agent.py +++ b/app/agent.py @@ -22,11 +22,14 @@ from langgraph.checkpoint.base import BaseCheckpointSaver from langgraph.types import Command from app.adk.roles import load_roles -from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory +from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory from app.checkpointing import open_checkpointer from app.config import Settings +from app.customer_case import record_intent from app.providers import ProviderBundle, load_provider from app.recorder import DatabaseRecorder, ExecutionRecorder +from app.skills.agent_skills import skill_version +from app.states.execution_state import check_customer_case from app.states.ledger import Ledger from app.tools.execution import ORCHESTRATOR from app.tools.local import TerraformRunner, local_tools @@ -62,6 +65,8 @@ class ExecutionEngine: max_revisions: int = 3, max_orchestrator_turns: int = 100, tool_factory: ToolFactory | None = None, + limiter: RunLimiter | None = None, + skill_versions: Mapping[str, str] | None = None, ) -> None: required = { ORCHESTRATOR, @@ -71,6 +76,7 @@ class ExecutionEngine: if missing: raise ValueError(f"Missing roles: {', '.join(missing)}") self._max_revisions = max_revisions + self._output_root = output_root self._graph = build_execution_graph( runtime=runtime, roles=roles, @@ -78,6 +84,8 @@ class ExecutionEngine: output_root=output_root, max_orchestrator_turns=max_orchestrator_turns, tool_factory=tool_factory, + limiter=limiter, + skill_versions=skill_versions, ).compile(checkpointer=checkpointer) async def start( @@ -85,6 +93,7 @@ class ExecutionEngine: workflow_request: str, *, session_id: str | None = None, + customer_case: str | None = None, pre_approved: bool = False, allow_cloud_read: bool | None = None, execution_id: str | None = None, @@ -92,14 +101,25 @@ class ExecutionEngine: ) -> Interaction: """Start an Execution. `scripted_answers` are (regex, answer) pairs a pre-approved Execution uses to answer questions, for evaluation runs.""" + customer_case = check_customer_case(customer_case) execution_id = execution_id or str(uuid.uuid4()) if await self._exists(execution_id): raise ValueError(f"Execution {execution_id} already exists") if pre_approved and allow_cloud_read is None: allow_cloud_read = False + session_id = session_id or str(uuid.uuid4()) + intent_version = record_intent( + self._output_root, + customer_case, + execution_id=execution_id, + session_id=session_id, + workflow_request=workflow_request, + ) initial: dict[str, Any] = { "execution_id": execution_id, - "session_id": session_id or str(uuid.uuid4()), + "session_id": session_id, + "customer_case": customer_case, + "intent_version": intent_version, "workflow_request": workflow_request, "pre_approved": pre_approved, "allow_cloud_read": allow_cloud_read, @@ -112,9 +132,12 @@ class ExecutionEngine: "pending_questions": [], "awaiting_questions": [], "answers": {}, + "drafts": {}, + "working": {}, "pending_permission": None, "prompt": None, "outcomes": [], + "refusals": [], "outcomes_applied": 0, "events_recorded": 0, "turns": 0, @@ -218,15 +241,18 @@ async def open_assembly( runner = TerraformRunner( binary=settings.TERRAFORM_BINARY, timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS, - plugin_cache_dir=settings.TF_PLUGIN_CACHE_DIR, + plugin_cache_dir=settings.terraform_plugin_cache(), ) offered = [name for names in bundle.tools.values() for name in names] + # One cap for Specialists and the pillar advisors they fan out to. + limiter = RunLimiter(settings.MAX_PARALLEL_SPECIALISTS) tool_factory = make_tool_factory( runtime, roles, bundle.pillar_skills, local_tools=local_tools(offered, runner), catalog=catalog, + limiter=limiter, ) async with open_checkpointer(settings) as checkpointer: @@ -239,5 +265,9 @@ async def open_assembly( max_revisions=settings.MAX_REVISIONS, max_orchestrator_turns=settings.MAX_ORCHESTRATOR_TURNS, tool_factory=tool_factory, + limiter=limiter, + skill_versions={ + name: skill_version(meta.path) for name, meta in bundle.skills.items() + }, ) yield Assembly(engine, bundle, roles, dict(catalog.gaps)) diff --git a/app/config.py b/app/config.py index 1605abd..1a112eb 100644 --- a/app/config.py +++ b/app/config.py @@ -38,7 +38,9 @@ class Settings(BaseSettings): # Local Terraform tools (fmt, validate, plan; never apply) TERRAFORM_BINARY: str = "terraform" TERRAFORM_TIMEOUT_SECONDS: float = 300 - TF_PLUGIN_CACHE_DIR: str | None = None + # Where Terraform providers are kept between checks, so they download once. + # Relative paths are under the repository root. Set it empty to disable the cache. + TF_PLUGIN_CACHE_DIR: str = ".cache/terraform-plugins" # Models: a request with no response in this time is abandoned and retried MODEL_TIMEOUT_SECONDS: float = 180 @@ -51,12 +53,21 @@ class Settings(BaseSettings): SPECIALIST_BUDGET: int = 15 MAX_REVISIONS: int = 3 MAX_ORCHESTRATOR_TURNS: int = 100 + # Agent runs in flight at once, pillar advisors included (model rate limits) + MAX_PARALLEL_SPECIALISTS: int = 4 CHECKPOINTER: str = "sqlite" # memory | sqlite | postgres CHECKPOINT_DB_PATH: str = "checkpoints.db" # Paths BASE_DIR: Path = Path(__file__).resolve().parent.parent + def terraform_plugin_cache(self) -> str | None: + """The provider cache directory as an absolute path; None when disabled.""" + if not self.TF_PLUGIN_CACHE_DIR.strip(): + return None + path = Path(self.TF_PLUGIN_CACHE_DIR).expanduser() + return str(path if path.is_absolute() else self.BASE_DIR / path) + def get_database_url(self) -> str: """Construct database connection URL (PostgreSQL or SQLite fallback).""" if self.DATABASE_URL: diff --git a/app/customer_case.py b/app/customer_case.py new file mode 100644 index 0000000..abb77c2 --- /dev/null +++ b/app/customer_case.py @@ -0,0 +1,105 @@ +"""A Customer case on disk: its intent and the history of that intent. + + deliverables/cases// + intent/ + 001.md, 002.md, ... each statement of what the customer wants, as given + history.json every statement in order, the Execution it started + and how that Execution ended + executions// what was generated for one statement + +The intent is recorded when an Execution starts, so a request is on record even if +nothing was delivered for it. history.json is the index of the case. +""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime +from pathlib import Path +from typing import Any + +from app.states.execution_state import case_dir + +INTENT_DIR = "intent" +HISTORY_FILENAME = "history.json" +IN_PROGRESS = "in_progress" + + +def intent_dir(output_root: Path, customer_case: str) -> Path: + return case_dir(output_root, customer_case) / INTENT_DIR + + +def read_history(output_root: Path, customer_case: str) -> dict[str, Any]: + """The case's intent history; empty when the case has none yet.""" + path = intent_dir(output_root, customer_case) / HISTORY_FILENAME + if path.is_file(): + try: + history = json.loads(path.read_text(encoding="utf-8")) + if isinstance(history, dict) and isinstance(history.get("intents"), list): + return history + except ValueError: + pass + return {"customer_case": customer_case, "intents": []} + + +def record_intent( + output_root: Path, + customer_case: str, + *, + execution_id: str, + session_id: str, + workflow_request: str, +) -> int: + """Record a new statement of the customer's intent and return its version.""" + folder = intent_dir(output_root, customer_case) + folder.mkdir(parents=True, exist_ok=True) + history = read_history(output_root, customer_case) + version = max((item["version"] for item in history["intents"]), default=0) + 1 + recorded_at = datetime.now(UTC).isoformat(timespec="seconds") + statement = f"{version:03d}.md" + (folder / statement).write_text( + f"# Intent {version}: {customer_case}\n\n" + f"- Recorded: {recorded_at}\n" + f"- Execution: `{execution_id}`\n\n" + f"## What the customer wants\n\n{workflow_request.strip()}\n", + encoding="utf-8", + ) + history["intents"].append( + { + "version": version, + "recorded_at": recorded_at, + "statement": f"{INTENT_DIR}/{statement}", + "workflow_request": workflow_request, + "execution_id": execution_id, + "session_id": session_id, + "status": IN_PROGRESS, + "execution": None, + } + ) + _write_history(folder, history) + return version + + +def close_intent( + output_root: Path, + customer_case: str, + *, + execution_id: str, + status: str, + has_files: bool, +) -> None: + """Record how the Execution started by an intent ended, and where its files are.""" + history = read_history(output_root, customer_case) + for item in history["intents"]: + if item.get("execution_id") == execution_id: + item["status"] = status + item["execution"] = f"executions/{execution_id}" if has_files else None + _write_history(intent_dir(output_root, customer_case), history) + return + + +def _write_history(folder: Path, history: dict[str, Any]) -> None: + folder.mkdir(parents=True, exist_ok=True) + (folder / HISTORY_FILENAME).write_text( + json.dumps(history, indent=2, ensure_ascii=False) + "\n", encoding="utf-8" + ) diff --git a/app/main.py b/app/main.py index bb11933..37902e6 100644 --- a/app/main.py +++ b/app/main.py @@ -68,9 +68,12 @@ def create_app( interaction = await assembly.engine.start( workflow_request, session_id=body.get("session_id"), + customer_case=body.get("customer_case"), pre_approved=True, allow_cloud_read=bool(body.get("allow_cloud_read", False)), ) + except ValueError as exc: + return JSONResponse({"error": str(exc)}, status_code=400) except Exception as exc: logger.exception("/generate failed") return JSONResponse( diff --git a/app/nodes/execution_nodes.py b/app/nodes/execution_nodes.py index 2852d6e..f2b79cd 100644 --- a/app/nodes/execution_nodes.py +++ b/app/nodes/execution_nodes.py @@ -6,10 +6,12 @@ append outcomes that the next Orchestrator turn applies in order. from __future__ import annotations +import dataclasses +import json import logging import re import time -from collections.abc import Awaitable, Callable, Mapping, Sequence +from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence from dataclasses import dataclass from pathlib import Path from typing import Any @@ -17,22 +19,32 @@ from typing import Any from langgraph.types import Command, Send, interrupt from app.adk.runtime import ( + REJECTION_PREFIXES, AgentRuntime, AgentTask, BudgetExhausted, NeedsInput, Outcome, RoleSpec, + RunLimiter, Stopped, Submitted, ToolFactory, ToolSpec, TurnEnded, ) +from app.customer_case import close_intent from app.recorder import ExecutionRecorder -from app.states.execution_state import ExecutionState +from app.states.execution_state import ( + UNASSIGNED_CASE, + ExecutionState, + execution_dir, + lessons_file, +) from app.states.ledger import Ledger, LedgerRefusal +from app.states.lessons import collect_lesson_candidates, refusal from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools +from app.workflows.chain import VERDICTS_FILE, validation_outcome from app.workflows.deliverables import ( DEPENDENCY_GRAPH, PHASE_ORDER, @@ -47,9 +59,12 @@ NO_USER_REPLY = ( "'Assumptions', and proceed." ) GUIDE_FILENAME = "solution-architecture-guide.md" +MANIFEST_FILENAME = "execution.json" # request, status and files of one Execution -def _no_tools(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]: +def _no_tools( + role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any] +) -> Sequence[ToolSpec]: return () @@ -73,9 +88,42 @@ def make_execution_nodes( output_root: Path, max_orchestrator_turns: int = 100, tool_factory: ToolFactory | None = None, + limiter: RunLimiter | None = None, + skill_versions: Mapping[str, str] | None = None, ) -> ExecutionNodes: tool_factory = tool_factory or _no_tools + def close(state: ExecutionState, status: str, *, has_files: bool) -> None: + close_intent( + output_root, + _case(state), + execution_id=state["execution_id"], + status=status, + has_files=has_files, + ) + + async def record_lessons( + state: ExecutionState, ledger: Ledger, status: str + ) -> None: + record = collect_lesson_candidates( + execution_id=state["execution_id"], + customer_case=_case(state), + status=status, + ledger=ledger, + outcomes=state.get("outcomes", []), + orchestrator_refusals=state.get("refusals", []), + role_skills={name: role.skills for name, role in roles.items()}, + skill_versions=skill_versions or {}, + ) + # Kept apart from deliverables/: an Execution that ends with warnings writes + # no Deliverable files, but what went wrong in it is still worth keeping. + path = lessons_file(output_root, state["execution_id"], _case(state)) + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text( + json.dumps(record, indent=2, ensure_ascii=False), encoding="utf-8" + ) + await recorder.record_lesson_candidates(state["execution_id"], record) + async def record_progress( state: ExecutionState, ledger: Ledger, status: str | None = None ) -> int: @@ -102,6 +150,7 @@ def make_execution_nodes( ledger.revisions(kind) for kind in DEPENDENCY_GRAPH ), "warnings": state.get("warnings", []), + "customer_case": _case(state), }, ) return len(ledger.events) @@ -113,6 +162,7 @@ def make_execution_nodes( notes = list(state.get("notes", [])) pending_permission = state.get("pending_permission") warnings = list(state.get("warnings", [])) + drafts = dict(state.get("drafts", {})) outcomes = state.get("outcomes", []) for record in outcomes[state.get("outcomes_applied", 0) :]: @@ -124,6 +174,7 @@ def make_execution_nodes( "content": record["content"], "attachments": record["attachments"], } + drafts.pop(kind.value, None) await recorder.record_submission( state["execution_id"], kind.value, @@ -143,6 +194,11 @@ def make_execution_nodes( "requested_by": [*requested, kind.value], } continue + if record.get("draft"): + drafts[kind.value] = { + "content": record["draft"], + "attachments": record.get("draft_attachments", {}), + } questions = record.get("questions") or [ ( f"The {record['role']} stopped: {record['summary']} " @@ -154,6 +210,7 @@ def make_execution_nodes( turns = state.get("turns", 0) + 1 update: dict[str, Any] = { "deliverables": deliverables, + "drafts": drafts, "pending_questions": pending_questions, "pending_permission": pending_permission, "outcomes_applied": len(outcomes), @@ -180,13 +237,21 @@ def make_execution_nodes( return finish_with("end_with_warnings", warnings=warnings) toolbox = OrchestratorToolbox(ledger, deliverables, pending_questions) + refusals = list(state.get("refusals", [])) + update["refusals"] = refusals task = AgentTask( role=ORCHESTRATOR, prompt="Decide the next step for this Execution using your tools.", - context=_orchestrator_context(state, ledger, pending_questions, notes), + context=_orchestrator_context( + state, ledger, deliverables, pending_questions, notes + ), ) started = time.monotonic() - outcome = await runtime.run(roles[ORCHESTRATOR], task, toolbox.tools()) + outcome = await runtime.run( + roles[ORCHESTRATOR], + task, + _noting_refusals(toolbox.tools(), refusals, ORCHESTRATOR, None), + ) logger.info( "[%s] orchestrator turn %d (%s phase) ended in %.0fs: %s", state["execution_id"], @@ -209,7 +274,9 @@ def make_execution_nodes( sends = [ Send( "specialist_task", - _specialist_input(state, ledger, deliverables, kind, attempt), + _specialist_input( + state, ledger, deliverables, drafts, kind, attempt + ), ) for kind, attempt in toolbox.started.items() ] @@ -257,10 +324,18 @@ def make_execution_nodes( async def specialist_task(task_input: dict[str, Any]) -> dict[str, Any]: role = roles[task_input["role"]] kind = DeliverableKind(task_input["kind"]) - tools = specialist_tools( - kind, - extra=tool_factory(role, kind.value), - allow_cloud_read=task_input["allow_cloud_read"], + working: dict[str, Any] = dict(task_input.get("working") or {}) + refusals: list[dict[str, Any]] = [] + tools = _noting_refusals( + specialist_tools( + kind, + extra=tool_factory(role, kind.value, working), + allow_cloud_read=task_input["allow_cloud_read"], + upstream=task_input["context"].get("dependencies"), + ), + refusals, + role.name, + kind.value, ) task = AgentTask( role=role.name, @@ -277,7 +352,11 @@ def make_execution_nodes( ) started = time.monotonic() try: - outcome: Outcome = await runtime.run(role, task, tools) + if limiter: + async with limiter.slot(): + outcome: Outcome = await runtime.run(role, task, tools) + else: + outcome = await runtime.run(role, task, tools) except Exception as exc: logger.exception("Specialist %s failed on %s", role.name, kind) outcome = Stopped(f"it failed with {type(exc).__name__}: {exc}") @@ -291,14 +370,18 @@ def make_execution_nodes( ) return { "outcomes": [ - _outcome_record(role.name, kind, task_input["attempt"], outcome) - ] + { + **_outcome_record(role.name, kind, task_input["attempt"], outcome), + "refusals": refusals, + } + ], + "working": {kind.value: working}, } async def await_user(state: ExecutionState) -> Command: prompt = state["prompt"] or {} if state.get("pre_approved"): - reply = _automatic_reply(prompt, state.get("scripted_answers", [])) + reply = automatic_reply(prompt, state.get("scripted_answers", [])) else: reply = interrupt(prompt) @@ -359,16 +442,17 @@ def make_execution_nodes( async def finalize(state: ExecutionState) -> dict[str, Any]: ledger = Ledger.from_dict(state["ledger"]) - _write_outputs( - output_root / "deliverables" / "executions" / state["execution_id"], - state.get("deliverables", {}), - ) + _write_outputs(output_root, state) + close(state, "completed", has_files=True) await record_progress(state, ledger, "completed") + await record_lessons(state, ledger, "completed") return {"status": "completed"} async def end_with_warnings(state: ExecutionState) -> dict[str, Any]: ledger = Ledger.from_dict(state["ledger"]) + close(state, "completed_with_warnings", has_files=False) await record_progress(state, ledger, "completed_with_warnings") + await record_lessons(state, ledger, "completed_with_warnings") return {"status": "completed_with_warnings"} return ExecutionNodes( @@ -383,6 +467,28 @@ def make_execution_nodes( # --- helpers --------------------------------------------------------------------------- +def _noting_refusals( + tools: Sequence[ToolSpec], + sink: list[dict[str, Any]], + role: str, + deliverable: str | None, +) -> list[ToolSpec]: + """The same tools, noting each reply that means the call did nothing.""" + + def noting(tool: ToolSpec) -> ToolSpec: + async def handler(**kwargs: Any) -> Any: + result = await tool.handler(**kwargs) + if result.outcome is None and result.message.startswith(REJECTION_PREFIXES): + sink.append( + refusal(role, deliverable, tool.name, tool.tier, result.message) + ) + return result + + return dataclasses.replace(tool, handler=handler) + + return [noting(tool) for tool in tools] + + def _summarise_outcome(outcome: Outcome) -> str: if isinstance(outcome, TurnEnded): return f"called {outcome.tool}" @@ -405,10 +511,19 @@ def _current_phase(ledger: Ledger) -> str: def _orchestrator_context( state: ExecutionState, ledger: Ledger, + deliverables: Mapping[str, Mapping[str, Any]], pending_questions: Sequence[Mapping[str, Any]], notes: Sequence[str], ) -> dict[str, Any]: + validation = deliverables.get(DeliverableKind.VALIDATION_RESULTS.value) return { + # The verdict on each Check, once validation is submitted: failed Checks are + # faults in the code; the rest are gaps in the Target architecture. + "validation": validation_outcome( + validation.get("attachments", {}).get(VERDICTS_FILE, "") + ) + if validation + else None, "workflow_request": state["workflow_request"], "pre_approved": bool(state.get("pre_approved")), "allow_cloud_read": state.get("allow_cloud_read"), @@ -438,6 +553,7 @@ def _specialist_input( state: ExecutionState, ledger: Ledger, deliverables: Mapping[str, Mapping[str, Any]], + drafts: Mapping[str, Mapping[str, Any]], kind: DeliverableKind, attempt: int, ) -> dict[str, Any]: @@ -448,15 +564,18 @@ def _specialist_input( "kind": kind.value, "attempt": attempt, "allow_cloud_read": state.get("allow_cloud_read"), + "working": dict(state.get("working", {}).get(kind.value, {})), "context": { "workflow_request": state["workflow_request"], "pre_approved": bool(state.get("pre_approved")), + "contract": spec.contract(), "dependencies": { dependency.value: dict(deliverables[dependency.value]) for dependency in inputs_of(kind) }, "feedback": list(ledger.feedback(kind)), "answers": list(state.get("answers", {}).get(kind.value, [])), + "draft": dict(drafts[kind.value]) if kind.value in drafts else None, "attempt": attempt, }, } @@ -479,6 +598,8 @@ def _outcome_record( "type": "needs_input", "questions": list(outcome.questions), "permission": outcome.permission, + "draft": outcome.draft, + "draft_attachments": dict(outcome.draft_attachments), } if isinstance(outcome, BudgetExhausted): return {**base, "type": "budget_exhausted", "summary": outcome.summary} @@ -495,7 +616,7 @@ def _describe_unfinished(outcome: Outcome) -> str: return f"Ended with an unexpected outcome: {type(outcome).__name__}." -def _automatic_reply( +def automatic_reply( prompt: Mapping[str, Any], scripted_answers: Sequence[Sequence[str]] = () ) -> dict[str, Any]: """The reply in a pre-approved Execution: approve, deny cloud reads, and answer @@ -543,18 +664,44 @@ def _render_prompt(prompt: Mapping[str, Any]) -> str: return "\n".join(item["question"] for item in prompt.get("questions", [])) -def _write_outputs( - out_dir: Path, deliverables: Mapping[str, Mapping[str, Any]] -) -> None: - out_dir.mkdir(parents=True, exist_ok=True) +def _case(state: ExecutionState) -> str: + return state.get("customer_case") or UNASSIGNED_CASE + + +def _write_outputs(output_root: Path, state: ExecutionState) -> None: + """Write a finished Execution's files under its Customer case, with a manifest + that ties the request to what was generated for it.""" + customer_case = _case(state) + execution_id = state["execution_id"] + out_dir = execution_dir(output_root, execution_id, customer_case) + deliverables: Mapping[str, Mapping[str, Any]] = state.get("deliverables", {}) + files: dict[str, str] = {} + by_kind: dict[str, dict[str, Any]] = {} guide = deliverables.get(DeliverableKind.SOLUTION_GUIDE.value) if guide: - (out_dir / GUIDE_FILENAME).write_text(guide["content"], encoding="utf-8") + files[GUIDE_FILENAME] = guide["content"] for kind, deliverable in deliverables.items(): - path = out_dir / "deliverables" / f"{kind}.md" + document = f"deliverables/{kind}.md" + files[document] = deliverable["content"] + attachments = dict(deliverable.get("attachments", {})) + files.update(attachments) + by_kind[kind] = {"document": document, "attachments": sorted(attachments)} + for name, content in files.items(): + path = out_dir / name path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(deliverable["content"], encoding="utf-8") - for name, content in deliverable.get("attachments", {}).items(): - attachment = out_dir / name - attachment.parent.mkdir(parents=True, exist_ok=True) - attachment.write_text(content, encoding="utf-8") + path.write_text(content, encoding="utf-8") + + manifest = { + "customer_case": customer_case, + "execution_id": execution_id, + "session_id": state.get("session_id"), + "intent_version": state.get("intent_version"), + "workflow_request": state["workflow_request"], + "status": "completed", + "solution_guide": GUIDE_FILENAME if guide else None, + "deliverables": by_kind, + } + out_dir.mkdir(parents=True, exist_ok=True) + (out_dir / MANIFEST_FILENAME).write_text( + json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8" + ) diff --git a/app/presentation.py b/app/presentation.py index eb28abf..6a0a014 100644 --- a/app/presentation.py +++ b/app/presentation.py @@ -27,6 +27,7 @@ def describe_prompt(prompt: Mapping[str, Any]) -> str: return ( f"Please review the {approval['phase']} Phase: {approval['summary']}\n\n" f"Deliverables: {', '.join(approval['deliverables'])}.\n\n" + f"{_describe_target_architecture(approval.get('target_architecture'))}" f"To approve, reply with the data {json.dumps(reply)}. " f"To request changes, reply with {json.dumps(changes)}. " "A text reply is recorded as conversation and never approves." @@ -46,6 +47,24 @@ def describe_prompt(prompt: Mapping[str, Any]) -> str: return "\n".join(lines) + "\n\nReply in text; answer every question you can." +def _describe_target_architecture(summary: Mapping[str, Any] | None) -> str: + """What the design Approval commits to: no code is written until it is granted.""" + if not summary: + return "" + text = ( + f"The Target architecture has {summary['elements']} Elements, " + f"{summary['relationships']} Relationships and {summary['checks']} Checks. " + "No infrastructure code is written until you approve it; the code is then " + "validated against those Checks.\n\n" + ) + for item in summary.get("not_applicable", []): + text += ( + f"Recommendation {item['recommendation']} is treated as not applicable: " + f"{item['reason']}\n" + ) + return text + ("\n" if summary.get("not_applicable") else "") + + def to_generate_response( interaction: Interaction, roles: Mapping[str, RoleSpec] ) -> dict[str, Any]: @@ -86,7 +105,7 @@ def to_generate_response( "requirements_doc": requirements, "architecture_doc": content(DeliverableKind.ARCHITECTURE_DESCRIPTION), "mermaid_diagram": attachment( - DeliverableKind.ARCHITECTURE_DIAGRAM, "architecture.mmd" + DeliverableKind.TARGET_ARCHITECTURE, "architecture.mmd" ), "terraform_code": attachment( DeliverableKind.DEPLOYMENT_GUIDANCE, "terraform/main.tf" diff --git a/app/recorder.py b/app/recorder.py index 6765b01..106a12b 100644 --- a/app/recorder.py +++ b/app/recorder.py @@ -8,6 +8,7 @@ Execution store (review candidate 03) replaces them. from __future__ import annotations import asyncio +import json import uuid from collections import defaultdict from collections.abc import Mapping, Sequence @@ -42,12 +43,22 @@ class ExecutionRecorder(Protocol): details: Mapping[str, Any], ) -> None: ... + async def record_lesson_candidates( + self, execution_id: str, record: Mapping[str, Any] + ) -> None: ... + class InMemoryRecorder: def __init__(self) -> None: self.events: dict[str, list[LedgerEvent]] = defaultdict(list) self.submissions: dict[str, list[dict[str, Any]]] = defaultdict(list) self.statuses: dict[str, list[dict[str, Any]]] = defaultdict(list) + self.lessons: dict[str, dict[str, Any]] = {} + + async def record_lesson_candidates( + self, execution_id: str, record: Mapping[str, Any] + ) -> None: + self.lessons[execution_id] = dict(record) async def record_events( self, execution_id: str, events: Sequence[LedgerEvent] @@ -154,3 +165,15 @@ class DatabaseRecorder: agent_name=SESSION_AGENT_NAME, state_data={"latest_execution_id": execution_id, "status": status}, ) + + async def record_lesson_candidates( + self, execution_id: str, record: Mapping[str, Any] + ) -> None: + await asyncio.to_thread( + self._db.save_artifact, + artifact_id=str(uuid.uuid4()), + execution_id=execution_id, + artifact_type="lesson_candidates", + file_path="lesson-candidates.json", + content=json.dumps(dict(record), ensure_ascii=False), + ) diff --git a/app/skills/agent_skills.py b/app/skills/agent_skills.py index d152f27..2981508 100644 --- a/app/skills/agent_skills.py +++ b/app/skills/agent_skills.py @@ -6,6 +6,7 @@ Agent Skills specification (https://agentskills.io/specification). from __future__ import annotations +import hashlib import re from collections.abc import Iterable from dataclasses import dataclass @@ -123,6 +124,15 @@ def read_skill(skill_dir: Path) -> SkillMeta: return SkillMeta(name=name, description=description, path=skill_dir) +def skill_version(skill_dir: Path) -> str: + """A short content hash of every file in the Skill, to say which Skill was loaded.""" + digest = hashlib.sha256() + for path in sorted(p for p in skill_dir.rglob("*") if p.is_file()): + digest.update(path.relative_to(skill_dir).as_posix().encode()) + digest.update(path.read_bytes()) + return digest.hexdigest()[:12] + + def discover_skills(directories: Iterable[Path]) -> dict[str, SkillMeta]: """Index every Skill that is an immediate child of one of `directories`. diff --git a/app/states/execution_state.py b/app/states/execution_state.py index 57105ac..f6e70eb 100644 --- a/app/states/execution_state.py +++ b/app/states/execution_state.py @@ -3,12 +3,58 @@ from __future__ import annotations import operator +import re +from pathlib import Path from typing import Annotated, Any, TypedDict +# A Customer case id becomes a directory name, so it is a short lowercase slug. +CUSTOMER_CASE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$") +# Executions started without a Customer case are grouped here, so every Execution's +# files sit under a case. +UNASSIGNED_CASE = "unassigned" + + +def check_customer_case(customer_case: object) -> str: + """The Customer case id, defaulting to UNASSIGNED_CASE; a ValueError when it is + not a safe slug.""" + if customer_case is None: + return UNASSIGNED_CASE + if not isinstance(customer_case, str) or not CUSTOMER_CASE.match(customer_case): + raise ValueError( + "customer_case must be 1 to 64 lowercase letters, digits or hyphens, " + f"starting and ending with a letter or digit; got {customer_case!r}" + ) + return customer_case + + +def case_dir(output_root: Path, customer_case: str) -> Path: + """Everything generated for one Customer case.""" + return output_root / "deliverables" / "cases" / customer_case + + +def execution_dir(output_root: Path, execution_id: str, customer_case: str) -> Path: + """Where one Execution's files go, under its Customer case.""" + return case_dir(output_root, customer_case) / "executions" / execution_id + + +def lessons_file(output_root: Path, execution_id: str, customer_case: str) -> Path: + return ( + output_root / "lessons" / "candidates" / customer_case / f"{execution_id}.json" + ) + + +def merge_by_key( + current: dict[str, dict[str, Any]] | None, update: dict[str, dict[str, Any]] | None +) -> dict[str, dict[str, Any]]: + """Parallel Specialist tasks each write their own Deliverable's entry.""" + return {**(current or {}), **(update or {})} + class ExecutionState(TypedDict, total=False): execution_id: str session_id: str + customer_case: str # the Customer case this Execution belongs to + intent_version: int # which statement of the case's intent started this Execution workflow_request: str pre_approved: bool allow_cloud_read: bool | None @@ -21,6 +67,11 @@ class ExecutionState(TypedDict, total=False): pending_questions: list[dict[str, Any]] # {kind, questions} not yet asked awaiting_questions: list[dict[str, Any]] # {kind, questions} asked, not answered answers: dict[str, list[dict[str, Any]]] # kind -> [{questions, reply}] + drafts: dict[ + str, dict[str, Any] + ] # kind -> {content, attachments} awaiting the user + # kind -> working memory its tools keep across attempts (e.g. pillar advice) + working: Annotated[dict[str, dict[str, Any]], merge_by_key] pending_permission: dict[str, Any] | None # {tier, requested_by} prompt: dict[str, Any] | None # what the user is being asked @@ -28,6 +79,7 @@ class ExecutionState(TypedDict, total=False): # applied to the Ledger by the next Orchestrator turn. outcomes: Annotated[list[dict[str, Any]], operator.add] outcomes_applied: int + refusals: list[dict[str, Any]] # the Orchestrator's refused tool calls events_recorded: int turns: int diff --git a/app/states/lessons.py b/app/states/lessons.py new file mode 100644 index 0000000..5f5d1ba --- /dev/null +++ b/app/states/lessons.py @@ -0,0 +1,125 @@ +"""Lesson candidates: what went wrong in an Execution and what was asked to fix it. + +Collected once, when the Execution ends, from what the Execution already holds: the +Ledger's events, the Specialists' outcome records and the tool refusals. They are raw +material for a reviewed change to a Skill, never memory carried into another Execution. +""" + +from __future__ import annotations + +from collections.abc import Mapping, Sequence +from typing import Any + +from app.states.ledger import Ledger +from app.workflows.chain import VERDICTS_FILE, validation_outcome +from app.workflows.deliverables import ( + DEPENDENCY_GRAPH, + DeliverableKind, + PhaseId, +) + +MESSAGE_LIMIT = 500 +_UNFINISHED = {"budget_exhausted", "stopped"} + + +def refusal( + role: str, deliverable: str | None, tool: str, tier: str, message: str +) -> dict[str, Any]: + """One tool refusal, as stored in Execution state. + + A cloud-read tool's message may describe the user's environment, so only its + leading words are kept. + """ + if tier == "cloud_read": + message = message.split(":", 1)[0] + return { + "role": role, + "deliverable": deliverable, + "tool": tool, + "message": message[:MESSAGE_LIMIT], + } + + +def collect_lesson_candidates( + *, + execution_id: str, + customer_case: str, + status: str, + ledger: Ledger, + outcomes: Sequence[Mapping[str, Any]], + orchestrator_refusals: Sequence[Mapping[str, Any]], + role_skills: Mapping[str, Sequence[str]], + skill_versions: Mapping[str, str], +) -> dict[str, Any]: + candidates: list[dict[str, Any]] = [] + + for event in ledger.events: + if event.type == "reopened": + candidates.append( + { + "type": "revision", + "deliverable": event.subject, + "reason": event.detail, + "requested_by": event.actor, + } + ) + elif event.type == "escalated": + candidates.append( + { + "type": "revision_limit", + "deliverable": event.subject, + "reason": event.detail, + } + ) + elif event.type == "changes_requested": + candidates.append( + { + "type": "change_request", + "phase": event.subject, + "deliverables": [ + kind.value + for kind, spec in DEPENDENCY_GRAPH.items() + if spec.phase is PhaseId(event.subject) + ], + "feedback": event.detail, + } + ) + elif event.type == "released" and event.detail in _UNFINISHED: + candidates.append( + { + "type": "unfinished", + "deliverable": event.subject, + "role": event.actor, + "reason": event.detail, + } + ) + + for record in outcomes: + for item in record.get("refusals", ()): + candidates.append({"type": "refusal", **item}) + if ( + record.get("type") == "submitted" + and record.get("kind") == DeliverableKind.VALIDATION_RESULTS.value + ): + outcome = validation_outcome( + record.get("attachments", {}).get(VERDICTS_FILE, "") + ) + attempt = record.get("attempt") + for kind, items in ( + ("failed_check", outcome["failed"]), + ("unverifiable_check", outcome["not_verifiable"]), + ("proposed_addition", outcome["proposed_additions"]), + ): + for item in items: + candidates.append({"type": kind, "attempt": attempt, **item}) + for item in orchestrator_refusals: + candidates.append({"type": "refusal", **item}) + + return { + "execution_id": execution_id, + "customer_case": customer_case, + "status": status, + "role_skills": {role: list(skills) for role, skills in role_skills.items()}, + "skill_versions": dict(skill_versions), + "candidates": candidates, + } diff --git a/app/tools/execution.py b/app/tools/execution.py index e40b253..2c31b58 100644 --- a/app/tools/execution.py +++ b/app/tools/execution.py @@ -28,8 +28,17 @@ from app.workflows.deliverables import ( check_submission, deliverables_in, ) +from app.workflows.target_architecture import ( + DIAGRAM_ATTACHMENT, + GRAPH_ATTACHMENT, + GraphError, + TargetArchitecture, + parse_graph, + render_mermaid, +) ORCHESTRATOR = "orchestrator" +_TARGET = DeliverableKind.TARGET_ARCHITECTURE CLOUD_READ = "cloud_read" _NO_ARGS: Mapping[str, Any] = {"type": "object", "properties": {}} @@ -186,10 +195,23 @@ class OrchestratorToolbox: "summary": summary, "deliverables": [kind.value for kind in deliverables_in(phase_id)], } + graph = self._target_architecture() + if graph and phase_id is DEPENDENCY_GRAPH[_TARGET].phase: + # What the user is approving before any code is written. + self.approval["target_architecture"] = graph.summary() return ToolResult( f"Asked the user to approve {phase_id}.", TurnEnded("request_approval") ) + def _target_architecture(self) -> TargetArchitecture | None: + deliverable = self._deliverables.get(_TARGET.value) + if not deliverable: + return None + try: + return parse_graph(deliverable.get("attachments", {})[GRAPH_ATTACHMENT]) + except (KeyError, GraphError): + return None + async def reopen(self, kind: str, reason: str) -> ToolResult: try: result = self.ledger.reopen( @@ -231,8 +253,13 @@ def specialist_tools( kind: DeliverableKind, extra: Sequence[ToolSpec], allow_cloud_read: bool | None, + upstream: Mapping[str, Mapping[str, Any]] | None = None, ) -> list[ToolSpec]: - """A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate.""" + """A Specialist's tools: submit, ask, and its role's tools with the cloud-read gate. + + `upstream` is the Deliverables this one builds on; with it, a submission's links + along the Requirements chain are checked. + """ async def submit_deliverable(content: str, attachments: Any = None) -> ToolResult: try: @@ -245,18 +272,34 @@ def specialist_tools( "attachment names must be relative paths without '..': " + ", ".join(unsafe) ) - missing = check_submission(kind, content, attachments) + missing = check_submission(kind, content, attachments, upstream) if missing: return ToolResult( "Not submitted. The Deliverable is missing: " + "; ".join(missing) ) + if kind is DeliverableKind.TARGET_ARCHITECTURE: + # The diagram is a view of the graph, so the engine draws it. + attachments[DIAGRAM_ATTACHMENT] = render_mermaid( + parse_graph(attachments[GRAPH_ATTACHMENT]) + ) return ToolResult(f"Submitted {kind}.", Submitted(content, attachments)) - async def needs_input(questions: Sequence[str]) -> ToolResult: + async def needs_input( + questions: Sequence[str], draft: str | None = None, attachments: Any = None + ) -> ToolResult: questions = tuple(q for q in questions if q) if not questions: return _refused("ask at least one question") - return ToolResult("Questions sent to the user.", NeedsInput(questions)) + try: + draft_attachments = files_from_argument(attachments) + except TypeError as exc: + return _refused(f"attachments: {exc}") + return ToolResult( + "Questions sent to the user.", + NeedsInput( + questions, draft=draft or None, draft_attachments=draft_attachments + ), + ) return [ ToolSpec( @@ -274,9 +317,15 @@ def specialist_tools( ), ToolSpec( "needs_input", - "Ask the user questions you can't proceed without. Ends your turn.", + "Ask the user questions you can't proceed without. Ends your turn. When " + "you are asking them to confirm a draft, pass it as `draft` (with its " + "`attachments`): it is returned to you with their answers.", _schema( - {"questions": {"type": "array", "items": {"type": "string"}}}, + { + "questions": {"type": "array", "items": {"type": "string"}}, + "draft": {"type": "string"}, + "attachments": FILES_SCHEMA, + }, ["questions"], ), needs_input, diff --git a/app/tools/local.py b/app/tools/local.py index 2ccb3af..5e8f61e 100644 --- a/app/tools/local.py +++ b/app/tools/local.py @@ -11,7 +11,7 @@ import os import re import tempfile from collections.abc import Awaitable, Callable, Iterable, Mapping -from dataclasses import dataclass +from dataclasses import dataclass, field from pathlib import Path, PurePosixPath from typing import Any @@ -76,7 +76,11 @@ async def mermaid_check(diagram: str) -> ToolResult: class TerraformRunner: binary: str = "terraform" timeout_seconds: float = 300 + # Providers are downloaded here once and reused by every later check. Without it, + # each validate or plan downloads its providers again into a scratch directory. plugin_cache_dir: str | None = None + # Terraform's plugin cache is not safe for concurrent installs. + _init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False) async def fmt(self, files: Mapping[str, str]) -> ToolResult: refusal = _check_files(files) @@ -147,9 +151,12 @@ class TerraformRunner: ) async def _init(self, root: Path) -> ToolResult | None: - code, output = await self._run( - [self.binary, "init", "-backend=false", "-input=false", "-no-color"], root - ) + command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"] + if self.plugin_cache_dir: + async with self._init_lock: + code, output = await self._run(command, root) + else: + code, output = await self._run(command, root) if code != 0: return ToolResult(_clip(f"terraform init failed:\n{output}")) return None @@ -159,7 +166,12 @@ class TerraformRunner: ) -> tuple[int, str]: environment = {**os.environ, "TF_IN_AUTOMATION": "1", **(env or {})} if self.plugin_cache_dir: - environment["TF_PLUGIN_CACHE_DIR"] = self.plugin_cache_dir + cache = Path(self.plugin_cache_dir).expanduser().resolve() + cache.mkdir(parents=True, exist_ok=True) + environment["TF_PLUGIN_CACHE_DIR"] = str(cache) + # Each check runs in a scratch directory with no dependency lock file. + # Without this, Terraform downloads a cached provider again to verify it. + environment["TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE"] = "true" try: process = await asyncio.create_subprocess_exec( *args, diff --git a/app/tools/pillars.py b/app/tools/pillars.py index 114f6e7..b37fb2c 100644 --- a/app/tools/pillars.py +++ b/app/tools/pillars.py @@ -1,25 +1,31 @@ """The design advisor's fan-out to one advisor per architecture-framework pillar. Pillar advice is working material for the design recommendations Deliverable, not a -Deliverable itself, so it never touches the Ledger. +Deliverable itself, so it never touches the Ledger. It is kept in that Deliverable's +working memory, so a Revision re-consults only the pillars its feedback touches. """ from __future__ import annotations import asyncio import dataclasses -from collections.abc import Mapping, Sequence +from collections.abc import Mapping, MutableMapping, Sequence +from contextlib import AsyncExitStack +from typing import Any from app.adk.runtime import ( AgentRuntime, AgentTask, RoleSpec, + RunLimiter, Submitted, ToolResult, ToolSpec, ) CONSULT_TOOL = "consult_pillar_advisors" +NO_GUIDANCE = "No guidance" +ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given def pillar_consultation_tool( @@ -27,8 +33,22 @@ def pillar_consultation_tool( advisor: RoleSpec, pillar_skills: Mapping[str, str], extra_tools: Sequence[ToolSpec] = (), + memory: MutableMapping[str, Any] | None = None, + limiter: RunLimiter | None = None, ) -> ToolSpec: - """A tool that runs one pillar advisor per pillar, in parallel, each with its Skill.""" + """A tool that runs one pillar advisor per pillar, in parallel, each with its Skill. + + With `memory`, advice is remembered: naming `pillars` re-consults only those and + returns the remembered advice for the rest. + """ + + async def advise(pillar: str, brief: str) -> str: + async with AsyncExitStack() as stack: + if limiter: + await stack.enter_async_context(limiter.slot()) + return await _advise( + runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools + ) async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult: chosen = list(pillars) if pillars else list(pillar_skills) @@ -38,20 +58,41 @@ def pillar_consultation_tool( f"Refused: unknown pillars {', '.join(unknown)}; " f"choose from {', '.join(pillar_skills)}" ) - results = await asyncio.gather( - *( - _advise( - runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools + async with AsyncExitStack() as stack: + if limiter: + # The calling Specialist only waits here, so its slot goes to advisors. + await stack.enter_async_context(limiter.lend()) + fresh = dict( + zip( + chosen, + await asyncio.gather(*(advise(pillar, brief) for pillar in chosen)), ) - for pillar in chosen ) + remembered: dict[str, str] = ( + dict(memory.get(ADVICE_KEY, {})) if memory is not None else {} ) - return ToolResult("\n\n".join(results)) + sections = [] + for pillar in pillar_skills: + if pillar in fresh: + advice = fresh[pillar] + if not advice.startswith(NO_GUIDANCE): + remembered[pillar] = advice + sections.append(f"## {pillar}\n\n{advice}") + elif pillar in remembered: + sections.append( + f"## {pillar} (from your earlier consultation)\n\n" + f"{remembered[pillar]}" + ) + if memory is not None: + memory[ADVICE_KEY] = remembered + return ToolResult("\n\n".join(sections)) return ToolSpec( CONSULT_TOOL, "Get guidance from one advisor per architecture-framework pillar, in parallel. " - "Give a brief with the workload, its requirements and the selected products.", + "Give a brief with the workload, its requirements and the selected products. " + "Omit `pillars` to consult every pillar afresh. Name `pillars` to re-consult " + "only those; advice already given for the others is returned unchanged.", { "type": "object", "properties": { @@ -84,12 +125,10 @@ async def _advise( try: outcome = await runtime.run(role, task, [_submit_advice_tool(), *extra_tools]) except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others - return f"## {pillar}\n\nNo guidance: the advisor failed ({exc})." + return f"{NO_GUIDANCE}: the advisor failed ({exc})." if isinstance(outcome, Submitted): - return f"## {pillar}\n\n{outcome.content.strip()}" - return ( - f"## {pillar}\n\nNo guidance: the advisor ended with {type(outcome).__name__}." - ) + return outcome.content.strip() + return f"{NO_GUIDANCE}: the advisor ended with {type(outcome).__name__}." def _submit_advice_tool() -> ToolSpec: diff --git a/app/tools/toolkit.py b/app/tools/toolkit.py index e46d075..7e03a41 100644 --- a/app/tools/toolkit.py +++ b/app/tools/toolkit.py @@ -7,10 +7,11 @@ Cloud-read gating is applied later, per Execution, by `specialist_tools`. from __future__ import annotations -from collections.abc import Mapping, Sequence +from collections.abc import Mapping, MutableMapping, Sequence +from typing import Any from app.adk.roles import PILLAR_ADVISOR -from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory, ToolSpec +from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory, ToolSpec from app.tools.mcp import McpCatalog from app.tools.pillars import pillar_consultation_tool from app.workflows.deliverables import DeliverableKind @@ -23,26 +24,41 @@ def make_tool_factory( *, local_tools: Sequence[ToolSpec] = (), catalog: McpCatalog | None = None, + limiter: RunLimiter | None = None, ) -> ToolFactory: local_by_name = {tool.name: tool for tool in local_tools} def mcp_tools(role: RoleSpec) -> list[ToolSpec]: return catalog.tools_for(role.mcp_servers) if catalog else [] - consult = None advisor = roles.get(PILLAR_ADVISOR) - if pillar_skills and advisor: - # Pillar advisors can't ask for permission, so they get general-tier tools only. - advisor_tools = [tool for tool in mcp_tools(advisor) if tool.tier == "general"] - consult = pillar_consultation_tool( - runtime, advisor, pillar_skills, extra_tools=advisor_tools - ) + # Pillar advisors can't ask for permission, so they get general-tier tools only. + advisor_tools = ( + [tool for tool in mcp_tools(advisor) if tool.tier == "general"] + if advisor + else [] + ) - def tools_for(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]: + def tools_for( + role: RoleSpec, deliverable: str | None, working: MutableMapping[str, Any] + ) -> Sequence[ToolSpec]: tools = [local_by_name[name] for name in role.tools if name in local_by_name] tools += mcp_tools(role) - if consult and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value: - tools.append(consult) + if ( + pillar_skills + and advisor + and deliverable == DeliverableKind.DESIGN_RECOMMENDATIONS.value + ): + tools.append( + pillar_consultation_tool( + runtime, + advisor, + pillar_skills, + extra_tools=advisor_tools, + memory=working, + limiter=limiter, + ) + ) return tools return tools_for diff --git a/app/workflows/chain.py b/app/workflows/chain.py new file mode 100644 index 0000000..8c00d7a --- /dev/null +++ b/app/workflows/chain.py @@ -0,0 +1,336 @@ +"""The data files along the Requirements chain, and what each must hold (ADR-0005). + + requirements.json requirements with ids + components.json components, and the requirements each serves + products.json the product selected for each component + recommendations.json design recommendations with ids + target-architecture.json the graph (see target_architecture.py) + implementation.json which code satisfies each Check + verdicts.json the validation verdict on each Check + +Each checker returns what is wrong, one entry per fault, so a Specialist can fix it +and submit again. `upstream` is the Deliverables a submission builds on, by kind; a +link to one of them is checked only when it is there. +""" + +from __future__ import annotations + +import json +from collections.abc import Mapping, Sequence +from typing import Any + +from app.workflows.target_architecture import ( + GRAPH_ATTACHMENT, + GraphError, + TargetArchitecture, + chain_gaps, + parse_graph, +) + +REQUIREMENTS_FILE = "requirements.json" +COMPONENTS_FILE = "components.json" +PRODUCTS_FILE = "products.json" +RECOMMENDATIONS_FILE = "recommendations.json" +IMPLEMENTATION_FILE = "implementation.json" +VERDICTS_FILE = "verdicts.json" + +REQUIREMENT_KINDS = ("functional", "non_functional") +VERDICTS = ("pass", "fail", "not_verifiable") +DRY_RUN_VERDICTS = ("pass", "fail", "not_run") + +Upstream = Mapping[str, Mapping[str, Any]] + + +def read_list(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]: + """An upstream data file as a list of objects; empty when absent or unreadable.""" + text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "") + try: + data = json.loads(text) + except ValueError: + return [] + return ( + [item for item in data if isinstance(item, dict)] + if isinstance(data, list) + else [] + ) + + +def read_graph(upstream: Upstream | None) -> TargetArchitecture | None: + text = ( + ((upstream or {}).get("target_architecture") or {}) + .get("attachments", {}) + .get(GRAPH_ATTACHMENT, "") + ) + try: + return parse_graph(text) + except GraphError: + return None + + +def _objects( + text: str, name: str, strings: Sequence[str], lists: Sequence[str] = () +) -> tuple[list[dict[str, Any]], list[str]]: + """The file's objects that have every required field, and what is wrong with it.""" + try: + data = json.loads(text) + except ValueError as exc: + return [], [f"{name}: not valid JSON ({exc})"] + if not isinstance(data, list): + return [], [f"{name}: must be a JSON list"] + accepted, problems = [], [] + for index, item in enumerate(data): + where = f"{name}[{index}]" + if not isinstance(item, dict): + problems.append(f"{where}: must be an object") + continue + missing = [ + field + for field in strings + if not isinstance(item.get(field), str) or not item[field].strip() + ] + missing += [ + field + for field in lists + if not isinstance(item.get(field), list) + or not all(isinstance(value, str) for value in item[field]) + ] + if missing: + problems.append(f"{where}: needs {', '.join(missing)}") + continue + accepted.append(item) + return accepted, problems + + +def _repeated( + items: Sequence[Mapping[str, Any]], name: str, key: str = "id" +) -> list[str]: + seen: set[str] = set() + problems = [] + for item in items: + if item[key] in seen: + problems.append(f"{name}: {key} {item[key]} is used more than once") + seen.add(item[key]) + return problems + + +def check_requirements( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = REQUIREMENTS_FILE + items, problems = _objects(attachments[name], name, ("id", "kind", "text")) + problems += _repeated(items, name) + problems += [ + f"{name}: {item['id']} kind must be one of {', '.join(REQUIREMENT_KINDS)}" + for item in items + if item["kind"] not in REQUIREMENT_KINDS + ] + if not items and not problems: + problems.append(f"{name}: lists no requirements") + return problems + + +def check_components( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = COMPONENTS_FILE + items, problems = _objects( + attachments[name], name, ("id", "name"), ("requirements",) + ) + problems += _repeated(items, name) + if not items and not problems: + problems.append(f"{name}: lists no components") + requirements = read_list(upstream, "requirements", REQUIREMENTS_FILE) + if requirements: + known = {item["id"] for item in requirements} + served: set[str] = set() + for item in items: + served.update(item["requirements"]) + problems += [ + f"{name}: {item['id']} serves {reference}, which is not a requirement" + for reference in item["requirements"] + if reference not in known + ] + problems += [ + f"{name}: functional requirement {item['id']} is served by no component" + for item in requirements + if item.get("kind") == "functional" and item["id"] not in served + ] + return problems + + +def check_products( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = PRODUCTS_FILE + items, problems = _objects(attachments[name], name, ("component", "product")) + components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE) + if components: + known = {item["id"] for item in components} + chosen = {item["component"] for item in items} + problems += [ + f"{name}: {item['component']} is not a component" + for item in items + if item["component"] not in known + ] + problems += [ + f"{name}: component {identifier} has no product selected" + for identifier in sorted(known - chosen) + ] + return problems + + +def check_recommendations( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = RECOMMENDATIONS_FILE + items, problems = _objects( + attachments[name], name, ("id", "pillar", "text"), ("components",) + ) + problems += _repeated(items, name) + if not items and not problems: + problems.append(f"{name}: lists no recommendations") + components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE) + if components: + known = {item["id"] for item in components} + problems += [ + f"{name}: {item['id']} names {reference}, which is not a component" + for item in items + for reference in item["components"] + if reference not in known + ] + return problems + + +def check_target_architecture( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + try: + graph = parse_graph(attachments[GRAPH_ATTACHMENT]) + except GraphError as exc: + return list(exc.problems) + if upstream is None: + return [] + return list( + chain_gaps( + graph, + requirements=read_list(upstream, "requirements", REQUIREMENTS_FILE), + components=read_list(upstream, "technical_decomposition", COMPONENTS_FILE), + products=read_list(upstream, "product_selection", PRODUCTS_FILE), + recommendations=read_list( + upstream, "design_recommendations", RECOMMENDATIONS_FILE + ), + ) + ) + + +def _covers_every_check( + items: Sequence[Mapping[str, Any]], name: str, graph: TargetArchitecture | None +) -> list[str]: + problems = _repeated(items, name, "check") + if graph is None: + return problems + given = {item["check"] for item in items} + problems += [ + f"{name}: {identifier} is not a Check in the Target architecture" + for identifier in sorted(given - set(graph.check_ids)) + ] + problems += [ + f"{name}: Check {identifier} is not accounted for" + for identifier in graph.check_ids + if identifier not in given + ] + return problems + + +def check_implementation( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = IMPLEMENTATION_FILE + items, problems = _objects(attachments[name], name, ("check", "file", "address")) + problems += _covers_every_check(items, name, read_graph(upstream)) + problems += [ + f"{name}: {item['check']} names {item['file']}, which is not attached" + for item in items + if item["file"] not in attachments + ] + return problems + + +def check_verdicts( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = VERDICTS_FILE + try: + data = json.loads(attachments[name]) + except ValueError as exc: + return [f"{name}: not valid JSON ({exc})"] + if not isinstance(data, dict): + return [ + f"{name}: must be an object with dry_run, checks and proposed_additions" + ] + problems: list[str] = [] + dry_run = data.get("dry_run") + if ( + not isinstance(dry_run, dict) + or dry_run.get("verdict") not in DRY_RUN_VERDICTS + or not isinstance(dry_run.get("evidence"), str) + or not dry_run["evidence"].strip() + ): + problems.append( + f"{name}.dry_run: needs a verdict ({', '.join(DRY_RUN_VERDICTS)}) and evidence" + ) + items, faults = _objects( + json.dumps(data.get("checks", [])), + f"{name}.checks", + ("check", "verdict", "evidence"), + ) + problems += faults + problems += [ + f"{name}.checks: {item['check']} verdict must be one of {', '.join(VERDICTS)}" + for item in items + if item["verdict"] not in VERDICTS + ] + problems += _covers_every_check(items, f"{name}.checks", read_graph(upstream)) + _, faults = _objects( + json.dumps(data.get("proposed_additions", [])), + f"{name}.proposed_additions", + ("statement", "applies_to", "reason"), + ) + return problems + faults + + +def validation_outcome(verdicts_text: str) -> dict[str, Any]: + """What a validation decided, for routing a Revision and for scoring. + + Failed Checks are faults in the code. A Check that could not be verified and a + proposed addition are gaps in the Target architecture. + """ + try: + data = json.loads(verdicts_text) + except ValueError: + data = {} + if not isinstance(data, dict): + data = {} + checks = [item for item in data.get("checks", []) if isinstance(item, dict)] + + def with_verdict(verdict: str) -> list[dict[str, Any]]: + return [ + {"check": item.get("check"), "evidence": item.get("evidence")} + for item in checks + if item.get("verdict") == verdict + ] + + dry_run = data.get("dry_run") if isinstance(data.get("dry_run"), dict) else {} + return { + "dry_run": dry_run, + "passed": [ + item.get("check") for item in checks if item.get("verdict") == "pass" + ], + "failed": with_verdict("fail"), + "not_verifiable": with_verdict("not_verifiable"), + "proposed_additions": [ + item + for item in data.get("proposed_additions", []) + if isinstance(item, dict) + ], + } diff --git a/app/workflows/deliverables.py b/app/workflows/deliverables.py index ac5f534..cf37e79 100644 --- a/app/workflows/deliverables.py +++ b/app/workflows/deliverables.py @@ -9,14 +9,34 @@ solution-guide template by suffix (e.g. "Products and features mapping" matches from __future__ import annotations import re -from collections.abc import Mapping +from collections.abc import Callable, Mapping from dataclasses import dataclass from enum import StrEnum +from app.workflows.chain import ( + COMPONENTS_FILE, + IMPLEMENTATION_FILE, + PRODUCTS_FILE, + RECOMMENDATIONS_FILE, + REQUIREMENTS_FILE, + VERDICTS_FILE, + Upstream, + check_components, + check_implementation, + check_products, + check_recommendations, + check_requirements, + check_target_architecture, + check_verdicts, +) +from app.workflows.target_architecture import GRAPH_ATTACHMENT + class PhaseId(StrEnum): REQUIREMENTS_DISCOVERY = "requirements_discovery" + # Design: ends with the Target architecture, approved before any code is written. SOLUTION_ARCHITECTURE = "solution_architecture" + SOLUTION_IMPLEMENTATION = "solution_implementation" SOLUTION_VALIDATION = "solution_validation" PACKAGING = "packaging" @@ -28,9 +48,9 @@ class DeliverableKind(StrEnum): REQUIREMENTS = "requirements" TECHNICAL_DECOMPOSITION = "technical_decomposition" PRODUCT_SELECTION = "product_selection" - ARCHITECTURE_DIAGRAM = "architecture_diagram" - ARCHITECTURE_DESCRIPTION = "architecture_description" DESIGN_RECOMMENDATIONS = "design_recommendations" + TARGET_ARCHITECTURE = "target_architecture" + ARCHITECTURE_DESCRIPTION = "architecture_description" DEPLOYMENT_GUIDANCE = "deployment_guidance" VALIDATION_RESULTS = "validation_results" SOLUTION_GUIDE = "solution_guide" @@ -45,6 +65,13 @@ class DeliverableSpec: sections: tuple[str, ...] = () attachments: tuple[str, ...] = () + def contract(self) -> dict[str, list[str]]: + """What a submission must contain, as plain data for the Specialist's context.""" + return { + "sections": list(self.sections), + "attachments": list(self.attachments), + } + _K = DeliverableKind @@ -61,12 +88,15 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = { "Current state", "Dependencies", ), + attachments=(REQUIREMENTS_FILE,), ), DeliverableSpec( _K.TECHNICAL_DECOMPOSITION, PhaseId.REQUIREMENTS_DISCOVERY, "decomposer", depends_on=(_K.REQUIREMENTS,), + sections=("Components",), + attachments=(COMPONENTS_FILE,), ), DeliverableSpec( _K.PRODUCT_SELECTION, @@ -74,19 +104,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = { "product-selector", depends_on=(_K.TECHNICAL_DECOMPOSITION,), sections=("Products and features mapping",), - ), - DeliverableSpec( - _K.ARCHITECTURE_DIAGRAM, - PhaseId.SOLUTION_ARCHITECTURE, - "diagrammer", - depends_on=(_K.PRODUCT_SELECTION,), - attachments=("architecture.mmd",), - ), - DeliverableSpec( - _K.ARCHITECTURE_DESCRIPTION, - PhaseId.SOLUTION_ARCHITECTURE, - "describer", - depends_on=(_K.ARCHITECTURE_DIAGRAM, _K.PRODUCT_SELECTION), + attachments=(PRODUCTS_FILE,), ), DeliverableSpec( _K.DESIGN_RECOMMENDATIONS, @@ -101,17 +119,38 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = { "Performance efficiency", "Sustainability", ), + attachments=(RECOMMENDATIONS_FILE,), + ), + DeliverableSpec( + _K.TARGET_ARCHITECTURE, + PhaseId.SOLUTION_ARCHITECTURE, + "target-architect", + depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS), + sections=("Elements", "Relationships", "Checks"), + # The engine adds architecture.mmd, rendered from the graph, on submission. + attachments=(GRAPH_ATTACHMENT,), + ), + DeliverableSpec( + _K.ARCHITECTURE_DESCRIPTION, + PhaseId.SOLUTION_IMPLEMENTATION, + "describer", + depends_on=(_K.TARGET_ARCHITECTURE,), + sections=("Components", "Flow"), ), DeliverableSpec( _K.DEPLOYMENT_GUIDANCE, - PhaseId.SOLUTION_ARCHITECTURE, + PhaseId.SOLUTION_IMPLEMENTATION, "iac-author", - depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS), + depends_on=(_K.TARGET_ARCHITECTURE,), sections=( "Deployment prerequisites", "Step-by-step deployment instructions", ), - attachments=("terraform/main.tf", "terraform/variables.tf"), + attachments=( + "terraform/main.tf", + "terraform/variables.tf", + IMPLEMENTATION_FILE, + ), ), DeliverableSpec( _K.VALIDATION_RESULTS, @@ -119,6 +158,7 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = { "validator", depends_on=(_K.DEPLOYMENT_GUIDANCE,), sections=("Deployment dry-run", "Architecture and policy analysis"), + attachments=(VERDICTS_FILE,), ), DeliverableSpec( _K.SOLUTION_GUIDE, @@ -139,6 +179,20 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = { ) } +# What each data file along the Requirements chain must hold, checked at submission. +DATA_CHECKS: Mapping[ + DeliverableKind, + tuple[str, Callable[[Mapping[str, str], Upstream | None], list[str]]], +] = { + _K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements), + _K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components), + _K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products), + _K.DESIGN_RECOMMENDATIONS: (RECOMMENDATIONS_FILE, check_recommendations), + _K.TARGET_ARCHITECTURE: (GRAPH_ATTACHMENT, check_target_architecture), + _K.DEPLOYMENT_GUIDANCE: (IMPLEMENTATION_FILE, check_implementation), + _K.VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts), +} + def inputs_of(kind: DeliverableKind) -> tuple[DeliverableKind, ...]: """The Deliverables a Specialist works from, in graph order. @@ -179,9 +233,16 @@ def _normalise(text: str) -> str: def check_submission( - kind: DeliverableKind, content: str, attachments: Mapping[str, str] + kind: DeliverableKind, + content: str, + attachments: Mapping[str, str], + upstream: Upstream | None = None, ) -> tuple[str, ...]: - """Return what a submission lacks against its contract; empty means it's complete.""" + """Return what a submission lacks against its contract; empty means it's complete. + + `upstream` is the Deliverables this one builds on, by kind. With it, the links + along the Requirements chain are checked too. + """ if not content.strip(): return ("content: must not be empty",) @@ -195,4 +256,10 @@ def check_submission( for name in spec.attachments: if name not in attachments: missing.append(f"attachment: {name}") + elif not attachments[name].strip(): + missing.append(f"attachment: {name} must not be empty") + if kind in DATA_CHECKS: + name, check = DATA_CHECKS[kind] + if attachments.get(name, "").strip(): + missing.extend(check(attachments, upstream)) return tuple(missing) diff --git a/app/workflows/execution_graph.py b/app/workflows/execution_graph.py index 19d184b..af42884 100644 --- a/app/workflows/execution_graph.py +++ b/app/workflows/execution_graph.py @@ -18,7 +18,7 @@ from typing import Any, cast from langgraph.graph import END, START, StateGraph -from app.adk.runtime import AgentRuntime, RoleSpec, ToolFactory +from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory from app.nodes.execution_nodes import make_execution_nodes from app.recorder import ExecutionRecorder from app.states.execution_state import ExecutionState @@ -32,6 +32,8 @@ def build_execution_graph( output_root: Path, max_orchestrator_turns: int = 100, tool_factory: ToolFactory | None = None, + limiter: RunLimiter | None = None, + skill_versions: Mapping[str, str] | None = None, ) -> StateGraph: nodes = make_execution_nodes( runtime=runtime, @@ -40,6 +42,8 @@ def build_execution_graph( output_root=output_root, max_orchestrator_turns=max_orchestrator_turns, tool_factory=tool_factory, + limiter=limiter, + skill_versions=skill_versions, ) graph = StateGraph(ExecutionState) diff --git a/app/workflows/target_architecture.py b/app/workflows/target_architecture.py new file mode 100644 index 0000000..6d80a0b --- /dev/null +++ b/app/workflows/target_architecture.py @@ -0,0 +1,283 @@ +"""The Target architecture: one explicit graph, established before code (ADR-0005). + + Elements every component and the resource that realises it + Relationships how Elements connect + Checks the numbered, verifiable conditions each must meet, each traced + to the requirement or design recommendation it comes from + +This module is pure: it parses the graph, states what is wrong with it, renders it as +a diagram, and says whether the Requirements chain through it is complete. +""" + +from __future__ import annotations + +import json +import re +from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass +from typing import Any + +GRAPH_ATTACHMENT = "target-architecture.json" +DIAGRAM_ATTACHMENT = "architecture.mmd" + + +@dataclass(frozen=True) +class Element: + id: str + name: str + product: str + resource_type: str + component: str | None = None # None for a supporting Element, e.g. an identity + + +@dataclass(frozen=True) +class Relationship: + id: str + source: str # "from" in the data + target: str # "to" in the data + kind: str + + +@dataclass(frozen=True) +class Check: + id: str + applies_to: str # an Element or Relationship id + statement: str + source: str # a requirement or design recommendation id + + +@dataclass(frozen=True) +class NotApplicable: + recommendation: str + reason: str + + +@dataclass(frozen=True) +class TargetArchitecture: + elements: tuple[Element, ...] + relationships: tuple[Relationship, ...] + checks: tuple[Check, ...] + not_applicable: tuple[NotApplicable, ...] = () + + @property + def check_ids(self) -> tuple[str, ...]: + return tuple(check.id for check in self.checks) + + def summary(self) -> dict[str, Any]: + """What a user approving the design is told about the graph.""" + return { + "elements": len(self.elements), + "relationships": len(self.relationships), + "checks": len(self.checks), + "not_applicable": [ + {"recommendation": item.recommendation, "reason": item.reason} + for item in self.not_applicable + ], + } + + +class GraphError(ValueError): + """The graph is not well-formed; `problems` says how, one entry per fault.""" + + def __init__(self, problems: Sequence[str]) -> None: + super().__init__("; ".join(problems)) + self.problems = tuple(problems) + + +def parse_graph(text: str) -> TargetArchitecture: + """Parse target-architecture.json, or raise GraphError naming every fault.""" + name = GRAPH_ATTACHMENT + try: + data = json.loads(text) + except ValueError as exc: + raise GraphError([f"{name}: not valid JSON ({exc})"]) from exc + if not isinstance(data, dict): + raise GraphError( + [f"{name}: must be an object with elements, relationships and checks"] + ) + + problems: list[str] = [] + + def items(key: str, required: Sequence[str]) -> list[dict[str, str]]: + raw = data.get(key, []) + if not isinstance(raw, list): + problems.append(f"{name}.{key}: must be a list") + return [] + accepted = [] + for index, item in enumerate(raw): + where = f"{name}.{key}[{index}]" + if not isinstance(item, dict): + problems.append(f"{where}: must be an object") + continue + missing = [ + field + for field in required + if not isinstance(item.get(field), str) or not item[field].strip() + ] + if missing: + problems.append(f"{where}: needs a non-empty {', '.join(missing)}") + continue + accepted.append(item) + return accepted + + elements = tuple( + Element( + id=item["id"], + name=item["name"], + product=item["product"], + resource_type=item["resource_type"], + component=item.get("component") or None, + ) + for item in items("elements", ("id", "name", "product", "resource_type")) + ) + relationships = tuple( + Relationship(item["id"], item["from"], item["to"], item["kind"]) + for item in items("relationships", ("id", "from", "to", "kind")) + ) + checks = tuple( + Check(item["id"], item["applies_to"], item["statement"], item["source"]) + for item in items("checks", ("id", "applies_to", "statement", "source")) + ) + not_applicable = tuple( + NotApplicable(item["recommendation"], item["reason"]) + for item in items("not_applicable", ("recommendation", "reason")) + ) + + if not elements and not problems: + problems.append(f"{name}.elements: the graph has no Elements") + + seen: set[str] = set() + ids = [thing.id for group in (elements, relationships, checks) for thing in group] + for identifier in ids: + if identifier in seen: + problems.append(f"{name}: id {identifier} is used more than once") + seen.add(identifier) + + element_ids = {element.id for element in elements} + for relationship in relationships: + for end, value in (("from", relationship.source), ("to", relationship.target)): + if value not in element_ids: + problems.append( + f"{name}: Relationship {relationship.id} {end} {value}, " + "which is not an Element" + ) + targets = element_ids | {relationship.id for relationship in relationships} + for check in checks: + if check.applies_to not in targets: + problems.append( + f"{name}: Check {check.id} applies to {check.applies_to}, " + "which is not an Element or Relationship" + ) + checked = {check.applies_to for check in checks} + for element in elements: + if element.id not in checked: + problems.append(f"{name}: Element {element.id} has no Check") + + if problems: + raise GraphError(problems) + return TargetArchitecture(elements, relationships, checks, not_applicable) + + +# --- the Requirements chain through the graph ---------------------------------------- + + +def chain_gaps( + graph: TargetArchitecture, + *, + requirements: Sequence[Mapping[str, Any]], + components: Sequence[Mapping[str, Any]], + products: Sequence[Mapping[str, Any]], + recommendations: Sequence[Mapping[str, Any]], +) -> tuple[str, ...]: + """Every place the Requirements chain stops before reaching a Check. + + A functional requirement is carried by a component that has an Element, or by a + Check of its own. A non-functional requirement and a design recommendation are + each a constraint, so each must be the source of a Check (a recommendation may + instead be marked not applicable, with a reason). + """ + gaps: list[str] = [] + requirement_ids = {item["id"] for item in requirements} + recommendation_ids = {item["id"] for item in recommendations} + sources = {check.source for check in graph.checks} + realised = {element.component for element in graph.elements if element.component} + + for check in graph.checks: + if check.source not in requirement_ids | recommendation_ids: + gaps.append( + f"Check {check.id} has source {check.source}, which is not a " + "requirement or design recommendation" + ) + for element in graph.elements: + if element.component and element.component not in {c["id"] for c in components}: + gaps.append( + f"Element {element.id} realises {element.component}, " + "which is not a component" + ) + + for component in components: + if component["id"] not in realised: + gaps.append(f"Component {component['id']} has no Element") + for requirement in requirements: + if requirement["id"] in sources: + continue + served = any( + requirement["id"] in component.get("requirements", ()) + and component["id"] in realised + for component in components + ) + if requirement.get("kind") == "functional" and served: + continue + gaps.append(f"Requirement {requirement['id']} has no Check") + for selection in products: + used = any( + element.component == selection["component"] + and element.product == selection["product"] + for element in graph.elements + ) + if not used: + gaps.append( + f"Product {selection['product']} selected for " + f"{selection['component']} appears on no Element" + ) + excused = {item.recommendation for item in graph.not_applicable} + for item in graph.not_applicable: + if item.recommendation not in recommendation_ids: + gaps.append( + f"not_applicable names {item.recommendation}, " + "which is not a design recommendation" + ) + for recommendation in recommendations: + if recommendation["id"] not in sources | excused: + gaps.append(f"Recommendation {recommendation['id']} has no Check") + return tuple(gaps) + + +# --- the diagram is a view of the graph ---------------------------------------------- + +_UNSAFE = re.compile(r'["\[\]{}()<>|`#;]') + + +def _label(*parts: str) -> str: + return "
".join(_UNSAFE.sub(" ", part).strip() for part in parts if part) + + +def _node_ids(ids: Iterable[str]) -> dict[str, str]: + """Mermaid-safe node ids; the graph's own ids may hold characters Mermaid rejects.""" + return {identifier: f"n{index}" for index, identifier in enumerate(ids)} + + +def render_mermaid(graph: TargetArchitecture) -> str: + """The architecture diagram: every Element and Relationship, exactly once.""" + nodes = _node_ids(element.id for element in graph.elements) + lines = ["flowchart LR"] + for element in graph.elements: + lines.append( + f' {nodes[element.id]}["{_label(element.name, element.product)}"]' + ) + for relationship in graph.relationships: + lines.append( + f" {nodes[relationship.source]} -->|{_label(relationship.kind)}| " + f"{nodes[relationship.target]}" + ) + return "\n".join(lines) + "\n" diff --git a/deliverables/as-is/source-architecture.md b/deliverables/as-is/source-architecture.md deleted file mode 100755 index 1c80e16..0000000 --- a/deliverables/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/as-is/source-architecture.mmd b/deliverables/as-is/source-architecture.mmd deleted file mode 100755 index 6d09aa7..0000000 --- a/deliverables/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.md b/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.mmd b/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/guides/solution-architecture-guide.md b/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.md b/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.mmd b/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/requirements.md b/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/requirements.md deleted file mode 100644 index 4bf6382..0000000 --- a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/validation/validation-results.md b/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/00acae17-3075-4e1a-b241-e377e825e425/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.md b/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.mmd b/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/guides/solution-architecture-guide.md b/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.md b/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.mmd b/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/requirements.md b/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/validation/validation-results.md b/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/034a1754-f4b5-4fe9-a3ee-523bf6e31ddf/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.md b/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.mmd b/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/guides/solution-architecture-guide.md b/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.md b/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.mmd b/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/requirements.md b/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/validation/validation-results.md b/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/03e95dc8-aac4-405d-a79f-2714b86fb0c5/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.md b/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.mmd b/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/guides/solution-architecture-guide.md b/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.md b/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.mmd b/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/requirements.md b/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/validation/validation-results.md b/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/0aa37f1f-d49e-49fc-8e98-db9911293457/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.md b/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.mmd b/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/guides/solution-architecture-guide.md b/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.md b/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.mmd b/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/requirements.md b/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/validation/validation-results.md b/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/0c1cfbfb-29ba-4c21-9cf1-92fe62ef4c01/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.md b/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.md deleted file mode 100755 index 44a1b22..0000000 --- a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Build an event-driven regional ingestion service (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.mmd b/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/guides/solution-architecture-guide.md b/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/guides/solution-architecture-guide.md deleted file mode 100755 index ae187c5..0000000 --- a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Build an event-driven regional ingestion service (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.md b/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.mmd b/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/requirements.md b/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/requirements.md deleted file mode 100755 index ddc14db..0000000 --- a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/validation/validation-results.md b/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/0e6a0334-4f8c-4d61-8450-72be243c953d/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.md b/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.mmd b/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/guides/solution-architecture-guide.md b/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.md b/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.mmd b/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/requirements.md b/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/validation/validation-results.md b/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/112fa94f-09e1-419d-a482-74ccf0aa385a/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.md b/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.md deleted file mode 100755 index fefbd77..0000000 --- a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: High scale ingestion workflow (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.mmd b/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/guides/solution-architecture-guide.md b/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/guides/solution-architecture-guide.md deleted file mode 100755 index 7526397..0000000 --- a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/guides/solution-architecture-guide.md +++ /dev/null @@ -1,150 +0,0 @@ -# Google Cloud Solution Architecture Guide - -## Executive Overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## Source vs Target Architecture (Before & After) - -### Before: Pre-existing Source Environment -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### After: Target Google Cloud Architecture -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -## Selected products -- **Compute**: Google Cloud Run -- **Messaging**: Google Cloud Pub/Sub -- **Storage**: Google Cloud Storage & Firestore -- **Identity & Access**: Google Cloud IAM Service Accounts - -## Architecture Diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Infrastructure Blueprint (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -## Validation results -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -## Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## Deployment & Operations Runbook -1. Initialize Terraform: `terraform init` -2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"` -3. Deploy Blueprint: `terraform apply` diff --git a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.md b/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.mmd b/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/requirements.md b/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/requirements.md deleted file mode 100755 index a416310..0000000 --- a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/validation/validation-results.md b/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/1261dc92-578d-44a7-972d-d79f05be2697/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.md b/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.mmd b/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/guides/solution-architecture-guide.md b/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.md b/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.mmd b/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/requirements.md b/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/validation/validation-results.md b/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/1422c792-c36f-4f43-b3a5-9960f44d9aaf/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.md b/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.mmd b/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/guides/solution-architecture-guide.md b/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.md b/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.mmd b/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/requirements.md b/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/validation/validation-results.md b/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/19bba6f5-36c7-4cd8-baa1-7f0df32a54eb/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.md b/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.mmd b/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/guides/solution-architecture-guide.md b/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.md b/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.mmd b/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/requirements.md b/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/validation/validation-results.md b/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/29c4024f-359b-451c-920e-3449b1a91245/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.md b/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.mmd b/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/guides/solution-architecture-guide.md b/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.md b/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.mmd b/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/requirements.md b/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/validation/validation-results.md b/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/2e8a856f-9656-40f3-a4dc-70bafe01d6ed/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.md b/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.mmd b/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/guides/solution-architecture-guide.md b/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.md b/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.mmd b/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/requirements.md b/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/validation/validation-results.md b/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/2fc3b2e6-ff92-4434-9041-ecfacef8e319/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.md b/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.mmd b/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/guides/solution-architecture-guide.md b/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.md b/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.mmd b/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/requirements.md b/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/validation/validation-results.md b/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/31a74fb0-bc40-4bbf-a17e-25e19368377a/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.md b/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.mmd b/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/guides/solution-architecture-guide.md b/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.md b/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.mmd b/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/requirements.md b/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/requirements.md deleted file mode 100644 index 4bf6382..0000000 --- a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/validation/validation-results.md b/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/39244c2c-2d22-46e8-8910-c36f497d33fb/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.md b/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.mmd b/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/guides/solution-architecture-guide.md b/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.md b/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.mmd b/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/requirements.md b/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/validation/validation-results.md b/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/40c3f168-01ce-44e3-8902-894bbd7376fa/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.md b/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.mmd b/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/guides/solution-architecture-guide.md b/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.md b/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.mmd b/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/requirements.md b/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/validation/validation-results.md b/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/43441680-3ef9-479f-988b-c3c13fb9d336/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.md b/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.mmd b/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/guides/solution-architecture-guide.md b/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.md b/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.mmd b/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/requirements.md b/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/validation/validation-results.md b/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/44b020bd-1f42-4807-a742-8f1c877b2167/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.md b/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.md deleted file mode 100755 index 44a1b22..0000000 --- a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Build an event-driven regional ingestion service (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.mmd b/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/guides/solution-architecture-guide.md b/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/guides/solution-architecture-guide.md deleted file mode 100755 index 7526397..0000000 --- a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/guides/solution-architecture-guide.md +++ /dev/null @@ -1,150 +0,0 @@ -# Google Cloud Solution Architecture Guide - -## Executive Overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## Source vs Target Architecture (Before & After) - -### Before: Pre-existing Source Environment -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### After: Target Google Cloud Architecture -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -## Selected products -- **Compute**: Google Cloud Run -- **Messaging**: Google Cloud Pub/Sub -- **Storage**: Google Cloud Storage & Firestore -- **Identity & Access**: Google Cloud IAM Service Accounts - -## Architecture Diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Infrastructure Blueprint (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -## Validation results -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -## Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## Deployment & Operations Runbook -1. Initialize Terraform: `terraform init` -2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"` -3. Deploy Blueprint: `terraform apply` diff --git a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.md b/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.mmd b/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/requirements.md b/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/requirements.md deleted file mode 100755 index ddc14db..0000000 --- a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/validation/validation-results.md b/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/48ce3d6f-8348-4905-89a8-2b73797c4956/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.md b/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.md deleted file mode 100644 index 79839ae..0000000 --- a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.md +++ /dev/null @@ -1,28 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `shining-hydra-367716`) - -## Live Resource Audit -- **Target Google Cloud Project**: `shining-hydra-367716` -- **Discovered Storage Buckets**: 2 GCS Bucket(s) -- **Discovered Compute Instances**: 1 Compute VM(s) -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: 1 Topic(s) -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -### Cloud Storage Buckets -- `b/example_123545_124345` (Location: `EUROPE-WEST2`, Storage Class: `STANDARD`) -- `b/shinning-hydra` (Location: `EUROPE-WEST2`, Storage Class: `NEARLINE`) - -### Compute Engine Instances -- VM `instance/instance-20251217-164317` (Zone: `europe-west2-c`, Type: `e2-medium`, Status: `RUNNING`) - -### Cloud Pub/Sub Topics -- Topic `pubsub/notification-events` - -### API Status Diagnostics -- `SERVICE_DISABLED`: `run.googleapis.com` is not enabled on project `shining-hydra-367716`. - -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.mmd b/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.mmd deleted file mode 100644 index 8c3955a..0000000 --- a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/as-is/source-architecture.mmd +++ /dev/null @@ -1,8 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: shining-hydra-367716"] - GCS0[("GCS: example_123545_124345")] - GCS1[("GCS: shinning-hydra")] - VM0["GCE: instance-20251217-164317"] - PubSub0["PubSub: notification-events"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/guides/solution-architecture-guide.md b/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/guides/solution-architecture-guide.md deleted file mode 100644 index 79d0b8e..0000000 --- a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/guides/solution-architecture-guide.md +++ /dev/null @@ -1,233 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `shining-hydra-367716`) - -## Live Resource Audit -- **Target Google Cloud Project**: `shining-hydra-367716` -- **Discovered Storage Buckets**: 2 GCS Bucket(s) -- **Discovered Compute Instances**: 1 Compute VM(s) -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: 1 Topic(s) -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -### Cloud Storage Buckets -- `b/example_123545_124345` (Location: `EUROPE-WEST2`, Storage Class: `STANDARD`) -- `b/shinning-hydra` (Location: `EUROPE-WEST2`, Storage Class: `NEARLINE`) - -### Compute Engine Instances -- VM `instance/instance-20251217-164317` (Zone: `europe-west2-c`, Type: `e2-medium`, Status: `RUNNING`) - -### Cloud Pub/Sub Topics -- Topic `pubsub/notification-events` - -### API Status Diagnostics -- `SERVICE_DISABLED`: `run.googleapis.com` is not enabled on project `shining-hydra-367716`. - -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: shining-hydra-367716"] - GCS0[("GCS: example_123545_124345")] - GCS1[("GCS: shinning-hydra")] - VM0["GCE: instance-20251217-164317"] - PubSub0["PubSub: notification-events"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.md b/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.mmd b/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/requirements.md b/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/requirements.md deleted file mode 100644 index 99ba7c4..0000000 --- a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Scan project shining-hydra-367716 and propose target serverless architecture - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/validation/validation-results.md b/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/4e1daf46-71f8-4f7f-a978-1ee6bab39cbf/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.md b/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.md deleted file mode 100755 index be66257..0000000 --- a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Discover and identify the current GCP environment state for project shining-hydra-367716 and propose target architecture migration. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.mmd b/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/guides/solution-architecture-guide.md b/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/guides/solution-architecture-guide.md deleted file mode 100755 index 0b7ed99..0000000 --- a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Discover and identify the current GCP environment state for project shining-hydra-367716 and propose target architecture migration. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.md b/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.mmd b/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/requirements.md b/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/requirements.md deleted file mode 100755 index 8408728..0000000 --- a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Discover and identify the current GCP environment state for project shining-hydra-367716 and propose target architecture migration. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/validation/validation-results.md b/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/5210ece6-364e-4746-855c-e5612842adfc/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.md b/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.md deleted file mode 100644 index 46372af..0000000 --- a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.mmd b/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.mmd deleted file mode 100644 index 15efbd4..0000000 --- a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/guides/solution-architecture-guide.md b/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/guides/solution-architecture-guide.md deleted file mode 100644 index 07fbe21..0000000 --- a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.md b/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.mmd b/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/requirements.md b/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/requirements.md deleted file mode 100644 index 14aad04..0000000 --- a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Perform live environment discovery scan for project shining-hydra-367716 and propose serverless target architecture migration - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/validation/validation-results.md b/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/52a4f886-29c4-45bc-b311-f1cfd481cdce/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.md b/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.mmd b/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/guides/solution-architecture-guide.md b/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.md b/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.mmd b/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/requirements.md b/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/validation/validation-results.md b/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/5407bc1a-2bac-455a-834c-81eaa39de54e/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.md b/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.mmd b/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/guides/solution-architecture-guide.md b/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.md b/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.mmd b/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/requirements.md b/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/validation/validation-results.md b/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/551fb584-e70b-4f65-80f2-f91f1d7bcd73/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.md b/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.mmd b/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/guides/solution-architecture-guide.md b/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.md b/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.mmd b/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/requirements.md b/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/validation/validation-results.md b/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/5c594162-73b0-487b-a4bf-6cd91401c0bf/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.md b/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.mmd b/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/guides/solution-architecture-guide.md b/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.md b/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.mmd b/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/requirements.md b/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/validation/validation-results.md b/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/5d45cecd-8370-4cee-a203-f41d63de8bd8/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.md b/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.mmd b/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/guides/solution-architecture-guide.md b/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.md b/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.mmd b/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/requirements.md b/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/validation/validation-results.md b/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/5dbccb58-2f54-496d-af50-c931cb91f94c/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.md b/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.md deleted file mode 100755 index dcd5663..0000000 --- a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-driven regional HTTP application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.mmd b/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/guides/solution-architecture-guide.md b/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/guides/solution-architecture-guide.md deleted file mode 100755 index 7526397..0000000 --- a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/guides/solution-architecture-guide.md +++ /dev/null @@ -1,150 +0,0 @@ -# Google Cloud Solution Architecture Guide - -## Executive Overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## Source vs Target Architecture (Before & After) - -### Before: Pre-existing Source Environment -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### After: Target Google Cloud Architecture -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -## Selected products -- **Compute**: Google Cloud Run -- **Messaging**: Google Cloud Pub/Sub -- **Storage**: Google Cloud Storage & Firestore -- **Identity & Access**: Google Cloud IAM Service Accounts - -## Architecture Diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Infrastructure Blueprint (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -## Validation results -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -## Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## Deployment & Operations Runbook -1. Initialize Terraform: `terraform init` -2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"` -3. Deploy Blueprint: `terraform apply` diff --git a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.md b/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.mmd b/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/requirements.md b/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/requirements.md deleted file mode 100755 index 81c6794..0000000 --- a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/validation/validation-results.md b/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/65cc189c-a604-4edf-b44a-3d45bf0b5763/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.md b/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.mmd b/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/guides/solution-architecture-guide.md b/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.md b/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.mmd b/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/requirements.md b/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/requirements.md deleted file mode 100644 index 973a2f5..0000000 --- a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/validation/validation-results.md b/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/670feeb5-7df7-4540-a139-77b3999d28d5/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.md b/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.mmd b/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/guides/solution-architecture-guide.md b/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.md b/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.mmd b/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/requirements.md b/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/validation/validation-results.md b/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/6d76f40e-b9ac-4c6e-bfa0-0055ae128b39/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.md b/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.md deleted file mode 100644 index 46372af..0000000 --- a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.mmd b/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.mmd deleted file mode 100644 index 15efbd4..0000000 --- a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/guides/solution-architecture-guide.md b/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/guides/solution-architecture-guide.md deleted file mode 100644 index 07fbe21..0000000 --- a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.md b/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.mmd b/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/requirements.md b/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/requirements.md deleted file mode 100644 index 67074a1..0000000 --- a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Discover current live GCP environment for project shining-hydra-367716 and propose target serverless architecture - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/validation/validation-results.md b/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/6e0f5819-12f4-4204-aca6-1792ee09432f/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.md b/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.md deleted file mode 100755 index dcd5663..0000000 --- a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-driven regional HTTP application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.mmd b/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/guides/solution-architecture-guide.md b/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/guides/solution-architecture-guide.md deleted file mode 100755 index d4ae96e..0000000 --- a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-driven regional HTTP application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.md b/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.mmd b/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/requirements.md b/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/requirements.md deleted file mode 100755 index 81c6794..0000000 --- a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/validation/validation-results.md b/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/70723dfc-9e40-482b-af29-88c2346f5a0f/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.md b/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.mmd b/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/guides/solution-architecture-guide.md b/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.md b/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.mmd b/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/requirements.md b/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/requirements.md deleted file mode 100644 index 973a2f5..0000000 --- a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/validation/validation-results.md b/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/72a73b87-e358-4e07-86ba-94f5136e91b7/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.md b/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.mmd b/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/guides/solution-architecture-guide.md b/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.md b/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.mmd b/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/requirements.md b/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/validation/validation-results.md b/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/792b29cd-e690-404a-b6b5-c687893d3f06/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.md b/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.md deleted file mode 100755 index cc61b22..0000000 --- a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.mmd b/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/guides/solution-architecture-guide.md b/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/guides/solution-architecture-guide.md deleted file mode 100755 index 102d6df..0000000 --- a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.md b/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.mmd b/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/requirements.md b/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/requirements.md deleted file mode 100755 index 973a2f5..0000000 --- a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/validation/validation-results.md b/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/79df8884-6d33-479d-8a98-5732b0eba1b7/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.md b/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.md deleted file mode 100644 index 46372af..0000000 --- a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.mmd b/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.mmd deleted file mode 100644 index 15efbd4..0000000 --- a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/guides/solution-architecture-guide.md b/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/guides/solution-architecture-guide.md deleted file mode 100644 index 07fbe21..0000000 --- a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.md b/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.mmd b/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/requirements.md b/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/requirements.md deleted file mode 100644 index bb02168..0000000 --- a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Live scan GCP project shining-hydra-367716 and propose modern serverless target architecture. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/validation/validation-results.md b/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/7e4118ff-7e9e-420c-bbd4-07f2d234fe7b/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.md b/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.md deleted file mode 100755 index cd01132..0000000 --- a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.mmd b/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/guides/solution-architecture-guide.md b/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/guides/solution-architecture-guide.md deleted file mode 100755 index 7526397..0000000 --- a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/guides/solution-architecture-guide.md +++ /dev/null @@ -1,150 +0,0 @@ -# Google Cloud Solution Architecture Guide - -## Executive Overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## Source vs Target Architecture (Before & After) - -### Before: Pre-existing Source Environment -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### After: Target Google Cloud Architecture -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -## Selected products -- **Compute**: Google Cloud Run -- **Messaging**: Google Cloud Pub/Sub -- **Storage**: Google Cloud Storage & Firestore -- **Identity & Access**: Google Cloud IAM Service Accounts - -## Architecture Diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Infrastructure Blueprint (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -## Validation results -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -## Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## Deployment & Operations Runbook -1. Initialize Terraform: `terraform init` -2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"` -3. Deploy Blueprint: `terraform apply` diff --git a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.md b/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.mmd b/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/requirements.md b/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/requirements.md deleted file mode 100755 index 4bf6382..0000000 --- a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/validation/validation-results.md b/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/7f88646d-15bd-4ee5-b6a6-289fb4d285b9/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.md b/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.md deleted file mode 100755 index cd01132..0000000 --- a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.mmd b/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/guides/solution-architecture-guide.md b/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/guides/solution-architecture-guide.md deleted file mode 100755 index d618b30..0000000 --- a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.md b/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.mmd b/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/requirements.md b/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/requirements.md deleted file mode 100755 index 4bf6382..0000000 --- a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/validation/validation-results.md b/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/809e4dc1-6a98-4fe8-a4b7-c36d72843fe6/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.md b/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.mmd b/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/guides/solution-architecture-guide.md b/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.md b/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.mmd b/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/requirements.md b/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/validation/validation-results.md b/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/9081e6e7-cda3-4d85-a243-b2ede584972a/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.md b/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.mmd b/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/guides/solution-architecture-guide.md b/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.md b/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.mmd b/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/requirements.md b/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/validation/validation-results.md b/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/922879b9-9622-4d86-b4da-01d50a5fc235/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.md b/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.mmd b/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/guides/solution-architecture-guide.md b/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.md b/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.mmd b/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/requirements.md b/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/validation/validation-results.md b/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/9690cccc-0cc6-4be2-ad4f-61ba5e5d714d/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.md b/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.md deleted file mode 100755 index 7646834..0000000 --- a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Test session retrieval route (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.mmd b/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/guides/solution-architecture-guide.md b/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/guides/solution-architecture-guide.md deleted file mode 100755 index 66fdd2a..0000000 --- a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Test session retrieval route (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.md b/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.mmd b/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/requirements.md b/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/requirements.md deleted file mode 100755 index 3fcc88c..0000000 --- a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/validation/validation-results.md b/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/9b03b388-3d6c-40a7-a626-8c2885fc93eb/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.md b/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.mmd b/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/guides/solution-architecture-guide.md b/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.md b/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.mmd b/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/requirements.md b/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/validation/validation-results.md b/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/9c9a0dea-53eb-494c-98b2-42986c22fa8b/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.md b/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.mmd b/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/guides/solution-architecture-guide.md b/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.md b/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.mmd b/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/requirements.md b/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/validation/validation-results.md b/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/9e13109d-2628-4cb3-884a-08950ee317a1/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.md b/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.mmd b/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/guides/solution-architecture-guide.md b/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.md b/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.mmd b/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/requirements.md b/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/validation/validation-results.md b/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/a1c12752-bd61-4f06-a21b-fc862e9017df/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.md b/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.mmd b/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/guides/solution-architecture-guide.md b/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.md b/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.mmd b/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/requirements.md b/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/validation/validation-results.md b/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/aaf682c8-078a-44e9-a484-98964334c9ea/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.md b/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.md deleted file mode 100755 index 7646834..0000000 --- a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Test session retrieval route (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.mmd b/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/guides/solution-architecture-guide.md b/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/guides/solution-architecture-guide.md deleted file mode 100755 index 7526397..0000000 --- a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/guides/solution-architecture-guide.md +++ /dev/null @@ -1,150 +0,0 @@ -# Google Cloud Solution Architecture Guide - -## Executive Overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## Source vs Target Architecture (Before & After) - -### Before: Pre-existing Source Environment -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### After: Target Google Cloud Architecture -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -## Selected products -- **Compute**: Google Cloud Run -- **Messaging**: Google Cloud Pub/Sub -- **Storage**: Google Cloud Storage & Firestore -- **Identity & Access**: Google Cloud IAM Service Accounts - -## Architecture Diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Infrastructure Blueprint (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -## Validation results -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -## Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## Deployment & Operations Runbook -1. Initialize Terraform: `terraform init` -2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"` -3. Deploy Blueprint: `terraform apply` diff --git a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.md b/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.mmd b/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/requirements.md b/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/requirements.md deleted file mode 100755 index 3fcc88c..0000000 --- a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/validation/validation-results.md b/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/ab632ed2-2ac6-4416-925b-f241bc442c5e/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.md b/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.md deleted file mode 100755 index 1c80e16..0000000 --- a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.mmd b/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.mmd deleted file mode 100755 index 6d09aa7..0000000 --- a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/guides/solution-architecture-guide.md b/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/guides/solution-architecture-guide.md deleted file mode 100755 index d7a7c45..0000000 --- a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.md b/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.mmd b/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/requirements.md b/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/requirements.md deleted file mode 100755 index a416310..0000000 --- a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/validation/validation-results.md b/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/ac2c78f7-4742-4e96-862f-77417b5ce71a/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.md b/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.mmd b/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/guides/solution-architecture-guide.md b/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.md b/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.mmd b/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/requirements.md b/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/requirements.md deleted file mode 100644 index 4bf6382..0000000 --- a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Design an event-driven regional HTTP application that accepts incoming webhooks, validates signatures, durably enqueues payloads to Pub/Sub, and retains raw events in Cloud Storage for 30-day replay audit. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/validation/validation-results.md b/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/b2a266d3-04dd-46ed-b7b9-e613c888dbcf/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.md b/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.mmd b/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/guides/solution-architecture-guide.md b/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.md b/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.mmd b/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/requirements.md b/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/validation/validation-results.md b/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/b49aee0b-03e3-4443-81b4-9b7f40848bde/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.md b/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.mmd b/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/guides/solution-architecture-guide.md b/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.md b/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.mmd b/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/requirements.md b/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/requirements.md deleted file mode 100644 index 973a2f5..0000000 --- a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/validation/validation-results.md b/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/b51e1fa7-d85b-4271-93b2-357655f5d363/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.md b/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.mmd b/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/guides/solution-architecture-guide.md b/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.md b/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.mmd b/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/requirements.md b/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/validation/validation-results.md b/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/c3c7597f-6414-4b35-9150-5a5b03c82f09/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.md b/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.mmd b/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/guides/solution-architecture-guide.md b/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.md b/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.mmd b/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/requirements.md b/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/validation/validation-results.md b/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/c8024aa0-1d2b-4dde-be18-b741f47c6c57/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.md b/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.md deleted file mode 100755 index 1c80e16..0000000 --- a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.mmd b/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.mmd deleted file mode 100755 index 6d09aa7..0000000 --- a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/guides/solution-architecture-guide.md b/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/guides/solution-architecture-guide.md deleted file mode 100755 index d7a7c45..0000000 --- a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.md b/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.mmd b/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/requirements.md b/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/requirements.md deleted file mode 100755 index 3fcc88c..0000000 --- a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/validation/validation-results.md b/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/c8b474ed-2107-4113-93ce-d45708511e18/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.md b/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.mmd b/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/guides/solution-architecture-guide.md b/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.md b/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.mmd b/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/requirements.md b/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/validation/validation-results.md b/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/ca903dd3-22fb-4329-b7c8-951c6f9e44fa/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.md b/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.mmd b/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/guides/solution-architecture-guide.md b/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.md b/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.mmd b/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/requirements.md b/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/validation/validation-results.md b/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/cfc23c8a-1272-4998-bcd0-a119d8d2a608/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.md b/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.md deleted file mode 100755 index fefbd77..0000000 --- a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: High scale ingestion workflow (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.mmd b/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/guides/solution-architecture-guide.md b/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/guides/solution-architecture-guide.md deleted file mode 100755 index 10e2910..0000000 --- a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: High scale ingestion workflow (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.md b/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.mmd b/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/requirements.md b/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/requirements.md deleted file mode 100755 index a416310..0000000 --- a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/validation/validation-results.md b/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/d01612ef-7169-413c-8594-503857f8e910/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.md b/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.mmd b/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/guides/solution-architecture-guide.md b/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.md b/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.mmd b/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/requirements.md b/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/validation/validation-results.md b/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/d575ef28-45d5-467a-a26c-4c4560278093/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.md b/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.mmd b/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/guides/solution-architecture-guide.md b/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.md b/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.mmd b/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/requirements.md b/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/validation/validation-results.md b/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/d9aa1985-6497-416f-ac49-57eb159a371a/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.md b/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.md deleted file mode 100644 index 46372af..0000000 --- a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.mmd b/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.mmd deleted file mode 100644 index 15efbd4..0000000 --- a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/guides/solution-architecture-guide.md b/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/guides/solution-architecture-guide.md deleted file mode 100644 index 07fbe21..0000000 --- a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/guides/solution-architecture-guide.md +++ /dev/null @@ -1,220 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Event-Driven Regional Application (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` - -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.md b/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.mmd b/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/requirements.md b/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/requirements.md deleted file mode 100644 index 9ef68a6..0000000 --- a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Perform live environment discovery scan for project shining-hydra-367716 and propose target serverless architecture - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/validation/validation-results.md b/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/dd6a89fa-0e88-49b1-b930-f4743908977f/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.md b/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.mmd b/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/guides/solution-architecture-guide.md b/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.md b/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.mmd b/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/requirements.md b/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/requirements.md deleted file mode 100644 index a416310..0000000 --- a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -High scale ingestion workflow - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/validation/validation-results.md b/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/ddd50279-f35e-4f3e-ac32-2b67fd1b1d2c/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.md b/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.md deleted file mode 100755 index cc61b22..0000000 --- a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.md +++ /dev/null @@ -1,18 +0,0 @@ -# Pre-emptive Source Environment Discovery (As-Is Architecture) - -## Existing Workload Audit -- **Workload Summary**: Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. (Legacy / Pre-existing Environment) -- **Current Hosting**: On-Premises Data Center / Legacy VM Infrastructure -- **Ingress Layer**: Self-managed NGINX Reverse Proxy listening on HTTP/HTTPS -- **Application Runtime**: Monolithic Application Instance (Single Point of Failure) -- **Database Layer**: Self-hosted PostgreSQL Instance (Unreplicated, Local Disk) -- **Queue / Messaging**: Local RabbitMQ Queue Instance - -## Current Operational Pain Points & Bottlenecks -- Single-instance compute leading to downtime during maintenance windows. -- Manual scaling capabilities unable to handle unexpected traffic spikes. -- Unencrypted local storage and unmanaged backups creating data loss risks. -- Elevated operational overhead and hardware lifecycle costs. - -## Source Component Topology -- `Client` -> `NGINX Proxy` -> `Monolith Application` -> `Local PostgreSQL / RabbitMQ` diff --git a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.mmd b/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.mmd deleted file mode 100755 index 15efbd4..0000000 --- a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] diff --git a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/guides/solution-architecture-guide.md b/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/guides/solution-architecture-guide.md deleted file mode 100755 index 7526397..0000000 --- a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/guides/solution-architecture-guide.md +++ /dev/null @@ -1,150 +0,0 @@ -# Google Cloud Solution Architecture Guide - -## Executive Overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## Source vs Target Architecture (Before & After) - -### Before: Pre-existing Source Environment -```mermaid -flowchart TD - Client[External Client] -->|HTTP/HTTPS| NginxProxy[Legacy NGINX Proxy] - NginxProxy --> MonolithApp[Monolithic Application VM] - MonolithApp --> LocalDB[(Self-Hosted PostgreSQL)] - MonolithApp --> LocalQueue[Local RabbitMQ Queue] -``` - -### After: Target Google Cloud Architecture -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -## Selected products -- **Compute**: Google Cloud Run -- **Messaging**: Google Cloud Pub/Sub -- **Storage**: Google Cloud Storage & Firestore -- **Identity & Access**: Google Cloud IAM Service Accounts - -## Architecture Diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -## Infrastructure Blueprint (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -## Validation results -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -## Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## Deployment & Operations Runbook -1. Initialize Terraform: `terraform init` -2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"` -3. Deploy Blueprint: `terraform apply` diff --git a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.md b/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.mmd b/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/requirements.md b/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/requirements.md deleted file mode 100755 index 973a2f5..0000000 --- a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/validation/validation-results.md b/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/e66e1bad-a3b8-4e7b-908e-c0c90c4b6632/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.md b/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.mmd b/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/guides/solution-architecture-guide.md b/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.md b/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.mmd b/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/requirements.md b/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/validation/validation-results.md b/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/ea300492-95ab-4122-b795-7819d5233c63/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.md b/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.md deleted file mode 100755 index 1c80e16..0000000 --- a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.mmd b/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.mmd deleted file mode 100755 index 6d09aa7..0000000 --- a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/guides/solution-architecture-guide.md b/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/guides/solution-architecture-guide.md deleted file mode 100755 index d7a7c45..0000000 --- a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.md b/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.mmd b/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/requirements.md b/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/requirements.md deleted file mode 100755 index 81c6794..0000000 --- a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/validation/validation-results.md b/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/ec767150-78f6-4266-ad20-1ca2b1e250e9/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.md b/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.mmd b/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/guides/solution-architecture-guide.md b/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.md b/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.mmd b/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/requirements.md b/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/requirements.md deleted file mode 100644 index ddc14db..0000000 --- a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/validation/validation-results.md b/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/eca9b8e6-2433-4370-a4da-481094c40ae6/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.md b/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.md deleted file mode 100755 index 1c80e16..0000000 --- a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.mmd b/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.mmd deleted file mode 100755 index 6d09aa7..0000000 --- a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/guides/solution-architecture-guide.md b/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/guides/solution-architecture-guide.md deleted file mode 100755 index d7a7c45..0000000 --- a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.md b/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.mmd b/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/requirements.md b/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/requirements.md deleted file mode 100755 index ddc14db..0000000 --- a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Build an event-driven regional ingestion service - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/validation/validation-results.md b/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/executions/f14699e6-bdec-48a5-b467-42439f53b1d4/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.md b/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.mmd b/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/guides/solution-architecture-guide.md b/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.md b/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.mmd b/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/requirements.md b/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/requirements.md deleted file mode 100644 index 81c6794..0000000 --- a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Event-driven regional HTTP application - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/validation/validation-results.md b/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/f2bd6892-888d-4d84-b1b1-3a4a5aaada37/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.md b/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.md deleted file mode 100644 index 1c80e16..0000000 --- a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.md +++ /dev/null @@ -1,15 +0,0 @@ -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. \ No newline at end of file diff --git a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.mmd b/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.mmd deleted file mode 100644 index 6d09aa7..0000000 --- a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/as-is/source-architecture.mmd +++ /dev/null @@ -1,5 +0,0 @@ -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject \ No newline at end of file diff --git a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/guides/solution-architecture-guide.md b/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/guides/solution-architecture-guide.md deleted file mode 100644 index d7a7c45..0000000 --- a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.md b/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.md deleted file mode 100644 index f83ff34..0000000 --- a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.mmd b/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.mmd deleted file mode 100644 index fdf15ac..0000000 --- a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/requirements.md b/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/requirements.md deleted file mode 100644 index 3fcc88c..0000000 --- a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Test session retrieval route - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/validation/validation-results.md b/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/validation/validation-results.md deleted file mode 100644 index 223c8f5..0000000 --- a/deliverables/executions/f9726b21-5668-43dd-9c22-f15a55d33111/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/deliverables/guides/solution-architecture-guide.md b/deliverables/guides/solution-architecture-guide.md deleted file mode 100755 index d7a7c45..0000000 --- a/deliverables/guides/solution-architecture-guide.md +++ /dev/null @@ -1,217 +0,0 @@ -# Google Cloud solution architecture: Event-Driven Regional Workload - -## 1. Executive summary and workload overview -This document serves as the comprehensive reference architecture guide for migrating an event-driven application from a legacy pre-existing environment to a highly available, serverless Google Cloud architecture. - -## 2. Requirements and current state - -### 2.1. Functional requirements -See [`docs/requirements.md`](docs/requirements.md). Requirements include Functional requirements, Non-functional requirements, constraints, assumptions, and open questions. -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Asynchronously publish domain events to Pub/Sub. -- Retain raw payload records in Cloud Storage for audit and replay. - -### 2.2. Non-functional requirements -- **Security**: HTTPS TLS 1.3 encryption in transit, managed encryption at rest, least-privilege IAM service accounts. -- **Reliability**: 99.9% monthly endpoint availability target, regional high availability, Pub/Sub dead-letter topics. -- **Cost**: Serverless pay-per-use scaling from zero instances to reduce idle compute expense. -- **Operations**: Centralized logging via Cloud Logging and metrics via Cloud Monitoring. -- **Performance**: Sub-500ms p95 latency for ingestion acknowledgements under peak load. -- **Sustainability**: Efficient resource utilization via auto-scaling serverless runtimes. - -### 2.3. Current state (As-Is Architecture) -# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`) - -## Live Resource Audit -- **Target Google Cloud Project**: `gcp-solution-architecture-demo` -- **Discovered Storage Buckets**: None / Default Bucket -- **Discovered Compute Instances**: None active -- **Discovered Database Instances**: None active -- **Discovered Pub/Sub Topics**: None active -- **Discovered Cloud Run Services**: None active - -## Resource Inventory Breakdown -## Current Operational Bottlenecks & Migration Drivers -- As-is infrastructure requires serverless auto-scaling and managed high availability. -- Need for declarative IaC management via Terraform. -- Transition to least-privilege IAM service identities and automated CI validation. - -```mermaid -flowchart TD - subgraph GCPProject["Google Cloud Project: gcp-solution-architecture-demo"] - EmptyProject["Project gcp-solution-architecture-demo (No Active Resources Detected)"] - end - Client[External Traffic] --> GCPProject -``` - -### 2.4. Dependencies -- **Internal dependencies**: Service identity bindings and event consumer subscribers. -- **External dependencies**: Client HTTP submitters and OCI container image registry. - -## 3. Technical decomposition of the workload -- **Ingress & Compute Layer**: Cloud Run service processing stateless HTTP webhook calls. -- **Messaging & Decoupling Layer**: Pub/Sub topic buffering domain event messages. -- **Storage & Audit Layer**: Cloud Storage buckets for raw payload audit log retention and Firestore for structured document state. - -## 4. Proposed solution architecture - -### 4.1. Google Cloud products and features mapping (Selected products) -| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | -| :--- | :--- | :--- | :--- | :--- | -| **Compute** | **Google Cloud Run** | Fully managed serverless execution with auto-scaling to zero ([Cloud Run Docs](https://cloud.google.com/run/docs/overview)) | GKE / Compute Engine MIGs | **Pros**: Granular cluster control
**Cons**: Higher operational overhead & idle costs | -| **Messaging** | **Google Cloud Pub/Sub** | Asynchronous regional event bus with at-least-once delivery ([Pub/Sub Docs](https://cloud.google.com/pubsub/docs/overview)) | Cloud Tasks / Kafka | **Pros**: Advanced queuing controls
**Cons**: Complex cluster management | -| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support
**Cons**: Less flexible scaling for unstructured event logs | - -### 4.2. Architecture diagram (Mermaid) -```mermaid -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic -``` - -### 4.3. Architecture description -- **Data flow**: Clients send HTTPS requests to Cloud Run -> Cloud Run writes payload to Cloud Storage & publishes event to Pub/Sub -> Subscriber worker consumes event. -- **Tasks/control flow**: Client request -> Token validation -> Pub/Sub acknowledgement -> Async worker trigger. - -## 5. Design and configuration recommendations - -### 5.1. Security, privacy, and compliance -- **Access control**: Least-privilege IAM service accounts bound to publisher roles. -- **Data protection**: Managed encryption at rest for Pub/Sub and Storage. -- **Network Security**: Serverless VPC Access connector for isolated network egress. - -### 5.2. Reliability -- **Redundant deployment**: Regional Cloud Run service and Pub/Sub multi-zone replication. -- **Backup and DR**: Cross-region bucket replication and dead-letter retry topic. - -### 5.3. Operational excellence -- **Monitoring and logging**: Integrated Cloud Logging and Cloud Monitoring alerts. -- **Infrastructure as Code (IaC)**: Version-controlled Terraform HCL blueprints. - -### 5.4. Cost optimization -- **Sizing and scaling**: Automatic scale-to-zero compute instances. - -### 5.5. Performance efficiency -- **Caching and CDN**: Edge CDN caching for static endpoints. - -### 5.6. Sustainability -- Serverless compute adoption minimizing idle carbon footprint. - -## 6. Deployment guidance - -### 6.1. Deployment prerequisites -- Enable required Google Cloud APIs (`run.googleapis.com`, `pubsub.googleapis.com`, `storage.googleapis.com`). -- Install Terraform >= 1.5.0 and Google Cloud SDK (`gcloud`). - -### 6.2. Step-by-step deployment instructions (Terraform) -```hcl -# Google Cloud Solution Architecture Baseline -terraform { - required_version = ">= 1.5.0" - required_providers { - google = { - source = "hashicorp/google" - version = "~> 5.0" - } - } -} - -provider "google" { - project = var.project_id - region = var.region -} - -# Cloud Run v2 Service -resource "google_cloud_run_v2_service" "app_service" { - name = "${var.environment}-app-service" - location = var.region - - template { - containers { - image = var.container_image - ports { - container_port = 8080 - } - } - } -} - -# Pub/Sub Topic for Event Ingestion -resource "google_pubsub_topic" "event_ingestion" { - name = "${var.environment}-event-ingestion-topic" - labels = { - environment = var.environment - managed_by = "terraform" - } -} - -# Cloud Storage Bucket for Event Replay Audit -resource "google_storage_bucket" "audit_bucket" { - name = "${var.project_id}-${var.environment}-audit-bucket" - location = var.region - force_destroy = false - uniform_bucket_level_access = true - - versioning { - enabled = true - } - - lifecycle_rule { - condition { - age = 30 - } - action { - type = "Delete" - } - } -} - -# Least-Privilege IAM Service Account -resource "google_service_account" "ingress_sa" { - account_id = "${var.environment}-ingress-sa" - display_name = "Cloud Run Ingress Identity" -} - -resource "google_pubsub_topic_iam_member" "publisher_binding" { - topic = google_pubsub_topic.event_ingestion.name - role = "roles/pubsub.publisher" - member = "serviceAccount:${google_service_account.ingress_sa.email}" -} -``` - -Apply blueprint instructions: -```bash -terraform -chdir=terraform init -terraform -chdir=terraform plan -var='project_id=YOUR_PROJECT_ID' -var='container_image=IMAGE_URI' -terraform -chdir=terraform apply -``` - -## 7. Validation plan (Validation results) -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings - -### Verification Checklist -- Step 4 guide persistence: non-empty solution-architecture-guide.md. -- Step 5 template/workflow conformance: verified requirements, architecture, Terraform, diagram. -- Step 6 & 7 publication & remote verification: complete. - -## 8. References -- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework) -- [Cloud Run Overview](https://cloud.google.com/run/docs/overview/what-is-cloud-run) -- [Cloud Pub/Sub Overview](https://cloud.google.com/pubsub/docs/overview) diff --git a/deliverables/target/architecture.md b/deliverables/target/architecture.md deleted file mode 100755 index f83ff34..0000000 --- a/deliverables/target/architecture.md +++ /dev/null @@ -1,21 +0,0 @@ -# Phase 1 — Architecture & Product Selection - -## Selected Products -- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution) -- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling) -- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay) -- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys) -- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting) - -## Component Responsibilities -1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted. -2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers. -3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting. - -## Security & Compliance -- HTTPS ingress with TLS 1.3 encryption in transit. -- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub. -- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`. - -## Grounded Documentation Citations (Google Developer Knowledge MCP) -- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run) diff --git a/deliverables/target/architecture.mmd b/deliverables/target/architecture.mmd deleted file mode 100755 index fdf15ac..0000000 --- a/deliverables/target/architecture.mmd +++ /dev/null @@ -1,6 +0,0 @@ -flowchart TD - Client[External HTTPS Client] -->|HTTPS POST /events| CloudRun[Google Cloud Run Service] - CloudRun -->|Publish Event| PubSubTopic[Cloud Pub/Sub Topic] - CloudRun -->|Write Raw Payload| GCSAudit[Cloud Storage Audit Bucket] - PubSubTopic -->|Push Delivery| EventConsumer[Cloud Run Consumer Service] - EventConsumer -->|Acknowledge| PubSubTopic diff --git a/deliverables/target/requirements.md b/deliverables/target/requirements.md deleted file mode 100755 index 973a2f5..0000000 --- a/deliverables/target/requirements.md +++ /dev/null @@ -1,44 +0,0 @@ -# Step 0 — Requirements discovery - -## Workflow request -Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation. - -## Functional requirements -- Accept authenticated HTTPS requests from external clients. -- Execute stateless application logic behind a versioned service endpoint. -- Publish asynchronous domain events from the application. -- Process events independently and tolerate retry/redelivery. -- Persist durable objects and application state separately. -- Expose operational logs, metrics, and audit-relevant events. -- Support repeatable infrastructure changes through declarative IaC. - -## Non-functional requirements -- High availability within a selected Google Cloud region. -- Horizontal scale for bursty HTTP traffic and asynchronous work. -- At-least-once event delivery with idempotent consumers. -- Encryption in transit and at rest using managed defaults initially. -- Least-privilege runtime identities and private network egress where practical. -- Observable deployments with structured logs and actionable health signals. -- Reproducible, reviewable, non-deployment validation in CI. - -## Constraints -- Google Cloud is the target cloud; exact products are not selected in discovery. -- Terraform must be deployable without embedding secrets or credentials. -- The baseline must not provision resources during validation. -- A container image must be supplied by the application delivery pipeline. -- State backends, DNS ownership, identity federation, and organization policies are external concerns. - -## Assumptions -- A single region is acceptable for the initial deployment. -- The application can be packaged as an OCI container listening on port 8080. -- Events can use at-least-once semantics and consumers can deduplicate. -- A dedicated Google Cloud project is available. -- Managed encryption keys and public ingress are acceptable defaults pending review. - -## Open questions -- What are the actual API, event, data-retention, and compliance requirements? -- Which clients and identity provider must authenticate requests? -- What are traffic, payload-size, latency, RTO, and RPO targets? -- Which data is relational, document, object, or analytical? - -**Product selection deferred:** `true` for this phase. diff --git a/deliverables/validation/validation-results.md b/deliverables/validation/validation-results.md deleted file mode 100755 index 223c8f5..0000000 --- a/deliverables/validation/validation-results.md +++ /dev/null @@ -1,14 +0,0 @@ -# Validation Results - -## Summary -- **Overall Validation Status**: PASS -- **Mermaid Diagram Syntax**: PASS -- **Terraform Structural Check**: PASS -- **Resource Provisioning Triggered**: False (Static non-deployment check enforced) - -## Verification Rules Checklist -- [x] Functional & Non-functional requirements specified -- [x] Product selection deferred during discovery and resolved in design phase -- [x] Regional High Availability and Security IAM boundaries configured -- [x] Mermaid diagram follows valid graph syntax -- [x] Terraform HCL declares provider, resources, and least-privilege IAM bindings diff --git a/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md b/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md index db7967e..3712f55 100644 --- a/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md +++ b/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md @@ -13,6 +13,8 @@ An Execution is a hierarchy of ReAct agents shaped by the dependencies between D The dependency graph is declared as data in code. The Orchestrator picks what to do next through tools that refuse work whose dependencies aren't met. Dependencies are guaranteed by code, while ordering and parallelism are the model's choice. +> **Under review (2026-10-07).** [ADR-0007](0007-jev-is-the-orchestrators-decision-point.md), proposed, would have the Orchestrator decide with Jev and run no language model. If accepted, it replaces "the Orchestrator ... is an ADK `LlmAgent`" above and reverses the third option rejected below. Specialists are unaffected. + ## Considered Options - **ADK end to end** (root `LlmAgent` with `sub_agents`/`AgentTool`, and ADK sessions for pauses): rejected. It departs from the KAB workflow standard, and LangGraph's checkpointed `interrupt()` is the proven platform path for resumable user Approvals. diff --git a/docs/adr/0004-lessons-and-overlays-arrive-as-skills.md b/docs/adr/0004-lessons-and-overlays-arrive-as-skills.md new file mode 100644 index 0000000..6d1cbd3 --- /dev/null +++ b/docs/adr/0004-lessons-and-overlays-arrive-as-skills.md @@ -0,0 +1,37 @@ +--- +status: proposed +--- + +# Lessons and overlays arrive as Skills + +An Execution starts clean ([CONTEXT.md](../../CONTEXT.md)) unless it is a Change request with a named Baseline ([ADR-0006](0006-a-change-request-starts-from-a-baseline-execution.md)), so nothing one Execution learns may flow into the next as hidden state. What an Execution gets wrong is still worth keeping. We decide that everything that changes how agents behave between Executions is a Skill change, of one of two kinds. + +- **Lessons.** Each Execution records **lesson candidates**: Revisions and their reasons, validator findings, tool refusals, the user's change requests, and work that stopped. An offline curator proposes lessons from candidates across Executions. A person approves each one. An approved lesson is added to a lessons Skill that the provider bundle assigns to roles. +- **Overlays.** An organisation's standards or one engagement's constraints are written as their own Skills. The provider bundle lists the ones every Execution loads. A caller may name further overlay Skills when it starts an Execution. + +Vendored Skills stay unmodified ([ADR-0002](0002-skills-are-the-portable-unit-of-behaviour.md)); lessons and overlays sit beside them. + +## Decisions to confirm + +This ADR is proposed. Accepting it means agreeing to each of these: + +1. **No lesson takes effect without a person's approval.** The curator proposes; it never edits a Skill that agents load. We prefer slower learning to an agent that rewrites its own instructions. +2. **A lesson must be shown to help.** It is kept only if the evaluation, run with and without it, holds quality and lowers Revisions, time or tokens. +3. **Lessons are per Cloud provider.** The lessons Skill is listed in that provider's bundle, since most lessons name its products. +4. **Overlay Skills come only from directories the deployment configures.** A caller names an overlay by its Skill name; it cannot upload one. Each passes the same Agent Skills validation as bundled Skills, and an unknown name refuses the Execution at the start. +5. **Every Execution records the Skills it loaded and a content hash of each,** so a result can be traced to the instructions that produced it. +6. **Lesson candidates are client data.** They quote user feedback and name resources. They are stored with the Execution's records, never in the repository, and a lesson is written so that it carries no client detail. + +## Considered Options + +- **Memory carried between Executions** (a vector store of past Deliverables or feedback, retrieved at run time): rejected. It breaks "every Execution starts clean", can leak one client's content into another's Execution, and cannot be reviewed or rolled back as a diff. +- **Automatic Skill edits** (the curator applies lessons directly): rejected for now. Without review, one bad Execution can degrade every later one, and nothing ties a regression to its cause. +- **Editing the vendored Skills in place**: rejected by ADR-0002. Upstream changes must arrive as a clean diff. +- **Overlays as prompt text passed by the caller**: rejected. Free text bypasses Skill validation and progressive loading, and it is an injection path. + +## Consequences + +- Learning is slow by design: a lesson reaches agents only after capture, proposal, review and an evaluation run. +- The evaluation must be able to see a difference a Skill makes. Its structural checks cannot, so the judged checks and the thresholds on Revisions, time and tokens become part of the loop. +- The glossary gains **Lesson candidate**, **Lesson** and **Overlay Skill** once this is accepted. +- Skills can no longer be loaded once at start-up for all Executions: the runtime must resolve a role's Skills per Execution. diff --git a/docs/adr/0005-the-target-architecture-is-an-explicit-graph.md b/docs/adr/0005-the-target-architecture-is-an-explicit-graph.md new file mode 100644 index 0000000..89475fe --- /dev/null +++ b/docs/adr/0005-the-target-architecture-is-an-explicit-graph.md @@ -0,0 +1,49 @@ +--- +status: accepted +--- + +# The target architecture is an explicit graph, and code comes after it + +Today the design passes from Specialist to Specialist as prose, and the infrastructure code is written before anyone has stated what it must satisfy. In an evaluation run on 2026-10-06 the validator found 4 problems, then 7, then 5 different ones, across three Revisions of the same Terraform: the bar was discovered after the code existed, and it moved. We decide that the **Target architecture** is one explicit graph, held as data, that is established before any infrastructure code is written, and that everything after it is derived from it and checked against it. + +The graph has three kinds of thing: + +- **Elements**: every component of the solution and the resource that realises it, with the product selected for it. +- **Relationships**: how Elements connect: calls, publishes to, reads from, is granted access to. +- **Checks**: on each Element and Relationship, the numbered, verifiable conditions it must meet. Each Check names the requirement or design recommendation it comes from. + +This makes the **Requirements chain** explicit: every requirement leads to the components that serve it, to the Elements and Checks that realise it, to the code that implements them, and to a validation verdict. A link that is missing is refused, not discovered later. + +## Who provides what + +The user states what they want to achieve, at a high level, in the Workflow request, and answers the questions that only they can answer. The agents produce everything in the graph: every Element, Relationship and Check is derived by Specialists from the requirements, the Cloud provider's architecture framework and its documented best practices. The user never writes or edits the graph. They approve it, from a summary, before code is written. + +## What changes + +- **A new Deliverable, the Target architecture,** follows product selection and design recommendations. Its graph is an attachment; its content is the readable summary. +- **Completeness is a submission rule.** The Target architecture is refused when a requirement, a selected product or a design recommendation has no Element or Check, or when a Relationship or Check refers to an Element that is not in the graph. +- **Later Deliverables are views of the graph.** The architecture diagram is rendered from its Elements and Relationships. The architecture description describes them. The deployment guidance implements every Element, Relationship and Check. +- **Validation is a verdict per Check,** pass or fail with evidence, not a list the validator composes on each pass. Something the validator notices that the graph lacks is a proposed addition to the Target architecture. It cannot fail the code. If it matters, the Target architecture is revised, and the code follows. + +## Decisions + +Accepted by the owner on 2026-10-07, with each of these: + +1. **The user approves the Target architecture before code is written.** The solution architecture Phase splits in two: design, which ends with the Target architecture, and implementation, which holds the deployment guidance. The upstream Skill has four Phases; this makes five, and is a deliberate departure from it. +2. **A new Specialist produces the Target architecture.** The design advisor stays responsible for recommendations only. +3. **Code renders the diagram from the graph.** No model draws it, so the picture cannot disagree with the architecture, and the diagrammer role goes. + +## Considered Options + +- **Keep the prose chain and tighten the validator's instructions**: rejected. The validator would still decide what to check after the code exists, and nothing would make two passes agree. +- **A build plan for the infrastructure code only**, beside the architecture: rejected. It would be a second description of the same system, free to drift from the diagram and the description. The graph has to be the architecture itself. +- **Let the infrastructure code be the model** and derive the diagram and checks from Terraform: rejected. It puts code first, which is the order that failed, and it ties the architecture to one infrastructure-as-code tool. +- **Raise the Revision limit**: rejected. It spends more on a loop that has no fixed target. + +## Consequences + +- Requirements reach code through data, not prose, so a requirement that nothing implements is caught when the Target architecture is submitted. +- A Revision either closes a known Check or it does not. Validation findings stop growing between passes. +- More is decided before code: the Specialist that writes the Target architecture carries work the infrastructure author and validator did implicitly, and a gap in the graph now costs a Revision of the Target architecture and everything after it. +- The Phase list is no longer the upstream Skill's. The solution guide still follows the upstream template; only where Approvals fall changes. +- The vocabulary of the graph is part of the glossary: Target architecture, Element, Relationship, Check, Requirements chain. "Dependency" keeps its existing meaning, between Deliverables. diff --git a/docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md b/docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md new file mode 100644 index 0000000..67e9402 --- /dev/null +++ b/docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md @@ -0,0 +1,40 @@ +--- +status: accepted +--- + +# A change request starts from a baseline Execution + +A user's requirements change after an architecture has been delivered. They need to say what has changed, at a high level, and get the architecture updated, not rebuilt from nothing with no link to what was agreed before. Today that is impossible by design: every Execution starts clean, and a Session or Customer case only groups Executions. We decide that a caller may start an Execution as a **Change request** against a **Baseline**: a completed Execution of the same Customer case. The new Execution begins from the Baseline's approved Deliverables and the user's description of what has changed, and it delivers a full, updated set plus a statement of what changed and why. + +This is the one, explicit exception to "every Execution starts clean". It is named by the caller, limited to the same Customer case, and recorded in the Execution's manifest. Nothing flows between Executions unless a Baseline is named. + +## How a Change request runs + +- **The user says what changed,** in the Workflow request, at the same high level as an original request: "retention goes from 30 days to 7 years", "it must now also serve a second region". It becomes the next statement in the Customer case's Intent history. +- **The agents work out the consequences.** The requirements analyst revises the Baseline's requirements, keeping every id that still holds and marking each requirement added, changed or removed. Each later Specialist starts from the Baseline's version of its Deliverable and changes only what the changed requirements reach. +- **The Requirements chain shows the reach.** Because requirements, components, Elements and Checks carry ids ([ADR-0005](0005-the-target-architecture-is-an-explicit-graph.md)), a changed requirement leads to the Elements and Checks it touches. Everything it does not reach is carried over unchanged. +- **The user approves the change, not the whole.** Each Approval shows what was added, changed and removed against the Baseline. +- **Validation covers every Check,** carried over or new, so an unchanged part that a change has broken is still caught. + +## Decisions + +Accepted by the owner on 2026-10-07, with each of these: + +1. **A Change request is a new Execution,** with its own id, Approvals and files. The Baseline is never modified, so every delivered version of a Customer case's architecture remains on record. +2. **The Baseline must be a completed Execution of the same Customer case.** One case can never start from another's work. +3. **The output is complete, not a patch.** A Change request delivers the full updated Deliverables and a change summary, so the latest Execution of a case always stands on its own. +4. **A Change request may itself be a Baseline,** so a case's Executions form a line of versions. + +## Considered Options + +- **Reopen the completed Execution** and revise its Deliverables in place: rejected. It destroys the record of what was delivered and approved, and an Execution that never ends cannot be audited. +- **Start clean and ask the user to restate everything** with the change included: rejected. It loses every decision and Approval already made, changes parts nobody asked to change, and gives no account of what differs. +- **Carry context automatically within a Customer case:** rejected. Hidden carry-over is what "starts clean" exists to prevent; the caller must choose the Baseline. +- **Deliver only a diff** of the Deliverables: rejected. The reader would have to assemble the current architecture from a chain of patches. + +## Consequences + +- "Every Execution starts clean" becomes "every Execution starts clean unless the caller names a Baseline". The glossary entries for Execution, Session and Customer case change to say so, and gain **Change request** and **Baseline**. +- This depends on ADR-0005. Without ids along the Requirements chain there is nothing to trace a change through, and a Change request would be a rewrite with extra context. +- A Change request against a Baseline produced by older Skills is revised under the Skills loaded now; the change summary can therefore include changes the user did not ask for. They must be shown as such. +- Lesson candidates gain a strong signal: what users change after delivery. diff --git a/docs/adr/0007-jev-is-the-orchestrators-decision-point.md b/docs/adr/0007-jev-is-the-orchestrators-decision-point.md new file mode 100644 index 0000000..2e89f2d --- /dev/null +++ b/docs/adr/0007-jev-is-the-orchestrators-decision-point.md @@ -0,0 +1,55 @@ +--- +status: proposed +--- + +# Jev is the Orchestrator's decision point + +[ADR-0003](0003-langgraph-holds-state-adk-agents-reason.md) made the Orchestrator a reasoning agent on a large language model. In practice its turns are slow and mostly mechanical: in the evaluation run of 2026-10-06 it took about 7 of 35 minutes, and stalled four times before doing the only thing available. We decide that the Orchestrator follows the agent-control pattern Vercel describes for Jev ([Jev in AI agent loops](https://vercel.com/i/jev-agent-control)): Jev, a decision model that answers typed questions with probabilities, proposes the next action; application code checks that it is allowed, carries it out and records it; a generative model only writes what the user reads. Specialists are unchanged: they still reason and write on language models. + +## Who owns what + +| Responsibility | Owner in the pattern | Here | +|---|---|---| +| Interpret the request | A model with supplied context | The requirements analyst and the Specialists after it | +| Propose the next action | The decision model | Jev, asked typed questions about the Execution's state | +| Check permission | Application code | The Ledger: Dependencies, Approvals, the Revision limit, the cloud-read gate | +| Execute the action | The tool runner | The Orchestrator's existing tools, called by code | +| Update state | Application code | The Execution graph and its checkpoint | +| Explain the result | A generative model | One small model call that writes an Approval summary or a question, from data it is given | + +## How a turn is decided + +1. **Code lists the allowed actions** from the Ledger and the Execution's state: relay waiting questions, act on a validation outcome, request an Approval, delegate ready work, finish. This is the permission check, and it holds whatever Jev answers, because a typed decision can still be wrong. +2. **Jev proposes the next action** from that list, and answers the other closed questions the turn needs, in one request where they rest on the same evidence: + - Did the user's last message ask for a change to submitted work? (yes or no) + - Which Deliverable does that change affect? (one of the Deliverables) + - What should happen after this validation: revise the code, revise the Target architecture, or proceed? (one of three) + A question whose options depend on another answer, or on evidence not yet fetched, is a second request. +3. **Code carries the decision out** through the existing tools and records it: the questions, the answers, their probabilities and what was done. A resumed Execution reuses a recorded decision when its input is unchanged. +4. **A generative model writes the reply**, only where the user reads prose: the summary they approve a Phase from, and any question the Orchestrator itself asks. It is given the decision and the data and decides nothing. + +Two guards from the pattern are kept in code. Repeated actions are limited, so the Orchestrator cannot loop on the same step: the turn limit and the Revision limit already do this. A failed call to Jev is recorded as a failure, distinct from an answer, so "Jev was unreachable" is never read as "nothing to do". + +## Decisions to confirm + +This ADR is proposed. Accepting it means agreeing to each of these: + +1. **No language model decides what the Orchestrator does.** Jev proposes and code disposes. A generative model writes user-facing text only. This replaces the part of ADR-0003 that makes the Orchestrator a reasoning agent. +2. **Low confidence goes to the user, not to another model.** Below a decision's threshold, an interactive Execution asks the user in plain terms; a pre-approved one takes the safest allowed action and records a warning. +3. **Jev being unreachable does not stop an Execution.** After a fixed retry budget the Orchestrator falls back to the fixed order of its seven steps, in code, and records that it did. +4. **What is sent to Jev is the Execution's state, not its content:** Deliverable names and statuses, Check ids and verdicts, and the user's latest message. Deliverable text and discovered cloud data are not sent for an Orchestrator decision. +5. **Jev does not choose Specialists.** Which Specialist produces a Deliverable is fixed by the dependency graph, and all ready work is delegated together. The pattern's specialist routing has nothing to route here. + +## Considered Options + +- **A smaller language model as Orchestrator:** rejected by the owner. It keeps the slow, open-ended turn and the stalls, at lower cost. +- **No generative model at all, with fixed wording for summaries and questions:** this ADR's first draft. Rejected to follow the pattern, which pairs Jev with a generative model for replies: an Approval summary is what a person decides from and reads better written than assembled. +- **Code only, with fixed rules:** rejected. It cannot tell what a user's free-text reply is asking for. +- **Code for the mechanical steps and the existing model for judgement:** rejected in favour of one decision point. It keeps two ways of deciding and the large model in the loop. + +## Consequences + +- The Orchestrator's instructions in `agents/orchestrator.md` become the wording of Jev's questions and the brief for the reply writer, held in a Skill or the provider bundle so they stay reviewable and portable. +- Jev becomes a dependency of every interactive Execution. Its availability, latency, rate limits and data retention must be known before this is built; none is documented publicly. +- Decisions become measurable: each has a confidence, so thresholds can be tuned from recorded Executions. +- An unusual request that fits none of the questions is handled by asking the user, where a language model might have improvised. diff --git a/eval/datasets/solution_cases.json b/eval/datasets/solution_cases.json index ff9966b..d26746d 100644 --- a/eval/datasets/solution_cases.json +++ b/eval/datasets/solution_cases.json @@ -194,5 +194,78 @@ "Approved. Please proceed." ] ] + }, + { + "id": "case-04-interactive-web-app", + "name": "Internal booking web application with a relational database (interactive)", + "workflow_request": "Design an internal web application on Google Cloud for staff to book meeting rooms and equipment, backed by a managed relational database, available only to employees signed in with the corporate identity provider, with application secrets kept out of code and configuration.", + "required_products": [ + "Cloud Run", + "Cloud SQL", + "Secret Manager" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "A single region, europe-west1 (Belgium). All users are in the EU." + ], + [ + "user|staff|employee|how many|concurren|traffic|volume|scale|peak|requests per|rps", + "About 4,000 employees; 300 concurrent users at the 09:00 peak, around 20 requests per second." + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover|backup", + "99.5% during business hours (07:00-19:00 CET). RTO 4 hours, RPO 1 hour. Daily backups kept 14 days." + ], + [ + "latency|response time|performance", + "Pages should load within 1 second at p95." + ], + [ + "identity|sign.?in|login|sso|auth|idp|access", + "Employees sign in with Google Workspace accounts; no access from outside the company. Admins are a Google group." + ], + [ + "security|compliance|encrypt|privacy|gdpr|secret|credential|password", + "GDPR applies to employee names and emails. Google-managed keys are fine. Database passwords and API keys must live in a secrets store and rotate every 90 days." + ], + [ + "data|database|schema|relational|postgres|mysql|size|storage", + "PostgreSQL. Under 20 GB of data in the first three years; bookings, rooms, equipment and audit history." + ], + [ + "cost|budget|spend", + "Under 600 EUR a month; the database can be small." + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "Bookings are kept in a shared spreadsheet today; there is no data to migrate." + ], + [ + "depend|integrat|calendar|email|notif|downstream|upstream", + "Send booking confirmation emails through the existing SMTP relay; no calendar integration in phase one." + ], + [ + "operat|monitor|logging|alert|team|support|deploy|ci|pipeline", + "Two developers own it, deploy containers from Cloud Build with Terraform, and want Cloud Monitoring alerts to a Google Chat space." + ], + [ + "network|vpc|private|internet|egress|ingress", + "No public database endpoint; the database must use private IP only." + ], + [ + "sustainab|carbon", + "No specific requirement." + ], + [ + "retention|audit|archive|delete", + "Keep booking history 2 years, then delete; keep audit logs 1 year." + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ] + ], + "interactive": true } ] diff --git a/eval/judge.py b/eval/judge.py new file mode 100644 index 0000000..5690f3f --- /dev/null +++ b/eval/judge.py @@ -0,0 +1,77 @@ +"""Judges: graded answers about a Deliverable that string matching cannot give. + +A judge takes a document and a set of questions and returns a score from 0 to 1 per +question. The shape (one state, many typed questions) is deliberately the one a +decision model takes, so the Gemini judge here can be swapped for one later. +""" + +from __future__ import annotations + +import json +from collections.abc import Mapping +from typing import Any, Protocol + +INSTRUCTIONS = ( + "You grade a document from a cloud solution architecture engagement. Answer every " + "question about the document only, strictly and without benefit of the doubt. " + 'Reply with one JSON object mapping each question id to a number: for a "yes_no" ' + 'question, 1 for yes and 0 for no; for a "graded" question, 0 (not at all), 0.33 ' + "(weakly), 0.67 (mostly) or 1 (fully)." +) + + +class Judge(Protocol): + async def answer( + self, document: str, questions: Mapping[str, Mapping[str, str]] + ) -> Mapping[str, float]: + """Score each question, keyed by id, from 0 to 1. + + `questions` maps an id to {"kind": "yes_no" | "graded", "text": ...}. + """ + ... + + +class GeminiJudge: + """A judge on the Gemini API or Vertex AI, chosen by the environment as ADK does.""" + + def __init__(self, model: str) -> None: + from google import genai + + self._client = genai.Client() + self._model = model + + async def answer( + self, document: str, questions: Mapping[str, Mapping[str, str]] + ) -> Mapping[str, float]: + from google.genai import types + + prompt = ( + f"{INSTRUCTIONS}\n\nQuestions:\n" + f"{json.dumps(dict(questions), indent=2, ensure_ascii=False)}\n\n" + f"Document:\n\n{document}\n" + ) + response = await self._client.aio.models.generate_content( + model=self._model, + contents=prompt, + config=types.GenerateContentConfig( + temperature=0, response_mime_type="application/json" + ), + ) + return parse_scores(response.text or "", questions) + + +def parse_scores(text: str, questions: Mapping[str, Any]) -> dict[str, float]: + """The judge's reply as scores; a missing or malformed answer scores 0.""" + try: + raw = json.loads(text) + except ValueError: + raw = {} + if not isinstance(raw, dict): + raw = {} + scores = {} + for key in questions: + value = raw.get(key, 0) + if isinstance(value, bool) or not isinstance(value, (int, float)): + value = 1.0 if value is True else 0.0 + scores[key] = min(1.0, max(0.0, float(value))) + return scores diff --git a/eval/scoring.py b/eval/scoring.py index 1908d99..ed3af43 100644 --- a/eval/scoring.py +++ b/eval/scoring.py @@ -2,10 +2,16 @@ Each check is a small, explainable rule tied to the upstream Skill's requirements. A case passes when its score reaches PASS_THRESHOLD. + +Structural checks always run. Judged checks (pillar checklist coverage, recommendation +quality) run when a judge is given, and are what lets a better or worse Skill move the +score. Thresholds on revisions, seconds and tokens turn a slower or costlier run into a +reported regression without changing the score. """ from __future__ import annotations +import json import re from collections.abc import Awaitable, Callable, Mapping, Sequence from dataclasses import dataclass, field @@ -15,9 +21,43 @@ from typing import Any from app.adk.runtime import ToolResult from app.agent import Interaction from app.tools.local import mermaid_check +from app.workflows.chain import ( + COMPONENTS_FILE, + PRODUCTS_FILE, + RECOMMENDATIONS_FILE, + REQUIREMENTS_FILE, + VERDICTS_FILE, + read_graph, + read_list, + validation_outcome, +) from app.workflows.deliverables import DeliverableKind +from app.workflows.target_architecture import ( + DIAGRAM_ATTACHMENT, + GRAPH_ATTACHMENT, + GraphError, + chain_gaps, + parse_graph, + render_mermaid, +) +from eval.judge import Judge PASS_THRESHOLD = 0.8 +CHECKLIST_COVERAGE = 0.7 # share of a pillar Skill's checklist the design must address +QUALITY_BAR = 0.67 # mean of the graded rubric: "mostly" or better +THRESHOLD_METRICS = ("revisions", "seconds", "tokens") + +# What a reviewer would ask of design recommendations, graded 0 to 1 each. +QUALITY_RUBRIC: Mapping[str, str] = { + "specific": "Are the recommendations specific to this workload and its stated " + "requirements, as opposed to generic best practice that would fit any workload?", + "actionable": "Does each recommendation name the concrete setting, feature or " + "configuration to apply, so an engineer could act on it without more research?", + "trade_offs": "Where pillars pull in different directions (for example cost " + "against reliability), is the trade-off named and a resolution recommended?", + "traceable": "Can each recommendation be traced to a requirement or constraint " + "of the workload?", +} TerraformValidate = Callable[[Mapping[str, str]], Awaitable[ToolResult]] _HEADING = re.compile(r"^(#{2,6})\s+(.+?)\s*$", re.MULTILINE) @@ -32,6 +72,11 @@ class CaseSpec: workflow_request: str required_products: tuple[str, ...] scripted_answers: tuple[tuple[str, str], ...] + # Run with a user in the loop (scripted): Approvals and questions are answered + # turn by turn, and Specialists are checked for asking before they submit. + interactive: bool = False + # Upper bounds for "revisions", "seconds" and "tokens"; exceeding one is a regression. + thresholds: Mapping[str, float] = field(default_factory=dict) @dataclass(frozen=True) @@ -62,8 +107,6 @@ class CaseResult: def load_cases(path: Path) -> list[CaseSpec]: - import json - return [ CaseSpec( id=item["id"], @@ -73,6 +116,8 @@ def load_cases(path: Path) -> list[CaseSpec]: scripted_answers=tuple( tuple(pair) for pair in item.get("scripted_answers", []) ), + interactive=bool(item.get("interactive", False)), + thresholds=dict(item.get("thresholds", {})), ) for item in json.loads(path.read_text(encoding="utf-8")) ] @@ -87,6 +132,53 @@ def template_headings(template: Path) -> list[str]: ] +def checklist_items(skill_file: Path) -> list[str]: + """The bullet items under a pillar Skill's "Validation checklist" heading.""" + text = skill_file.read_text(encoding="utf-8") + match = re.search( + r"^##\s+Validation checklist\s*$(.*?)(?=^##\s|\Z)", + text, + re.MULTILINE | re.DOTALL, + ) + if not match: + return [] + # Bullets may nest: a bullet with deeper bullets under it is a category, and the + # items to check are the leaves, each prefixed with its category. + bullets: list[tuple[int, str]] = [] + for line in match.group(1).splitlines(): + bullet = re.match(r"^(\s*)[-*]\s+(.*)$", line) + if bullet: + text = re.sub(r"^\[[ xX]?\]\s*", "", bullet.group(2).strip()) + bullets.append((len(bullet.group(1)), text.replace("**", ""))) + elif bullets and line.startswith(" ") and line.strip(): + indent, text = bullets[-1] + bullets[-1] = (indent, f"{text} {line.strip()}") + + items: list[str] = [] + category = "" + for index, (indent, text) in enumerate(bullets): + has_children = index + 1 < len(bullets) and bullets[index + 1][0] > indent + if has_children: + category = text.rstrip(":").strip() + elif indent == 0: + category = "" + items.append(text) + else: + items.append(f"{category}: {text}" if category else text) + return items + + +def regressions(case: CaseSpec, measured: Mapping[str, float | None]) -> list[str]: + """Each threshold the run exceeded, as "metric: measured > limit".""" + over = [] + for metric in THRESHOLD_METRICS: + limit = case.thresholds.get(metric) + value = measured.get(metric) + if limit is not None and value is not None and value > limit: + over.append(f"{metric}: {value:g} > {limit:g}") + return over + + def _normalise(text: str) -> str: return " ".join(_NUMBERING.sub("", text.strip().lower()).split()) @@ -103,6 +195,10 @@ async def score_execution( interaction: Interaction, headings: Sequence[str], terraform_validate: TerraformValidate, + *, + judge: Judge | None = None, + pillar_checklists: Mapping[str, Sequence[str]] | None = None, + timeline: Sequence[Mapping[str, Any]] = (), ) -> CaseResult: deliverables: Mapping[str, Mapping[str, Any]] = interaction.state.get( "deliverables", {} @@ -179,7 +275,7 @@ async def score_execution( ) ) - diagram = attachments(DeliverableKind.ARCHITECTURE_DIAGRAM).get( + diagram = attachments(DeliverableKind.TARGET_ARCHITECTURE).get( "architecture.mmd", "" ) mermaid = await mermaid_check(diagram) @@ -204,4 +300,129 @@ async def score_execution( terraform_ok, terraform_detail = False, "no Terraform files attached" checks.append(Check("terraform_validates", terraform_ok, terraform_detail)) + checks.append(_chain_check(deliverables)) + checks.append(_verdicts_check(attachments(DeliverableKind.VALIDATION_RESULTS))) + checks.append( + _diagram_matches_graph(attachments(DeliverableKind.TARGET_ARCHITECTURE)) + ) + + if case.interactive: + checks.append(_asks_before_submitting(timeline)) + + if judge is not None: + recommendations = content(DeliverableKind.DESIGN_RECOMMENDATIONS) + checks.append( + await _checklist_coverage(judge, recommendations, pillar_checklists or {}) + ) + checks.append(await _quality(judge, recommendations)) + return CaseResult(case.id, interaction.status, tuple(checks)) + + +def _chain_check(deliverables: Mapping[str, Mapping[str, Any]]) -> Check: + """The Requirements chain holds end to end: every requirement reaches a Check, + directly or through a component's Element, and nothing along it is missing.""" + name = "requirements_chain_complete" + graph = read_graph(deliverables) + if graph is None: + return Check(name, False, "no well-formed Target architecture") + gaps = chain_gaps( + graph, + requirements=read_list(deliverables, "requirements", REQUIREMENTS_FILE), + components=read_list(deliverables, "technical_decomposition", COMPONENTS_FILE), + products=read_list(deliverables, "product_selection", PRODUCTS_FILE), + recommendations=read_list( + deliverables, "design_recommendations", RECOMMENDATIONS_FILE + ), + ) + return Check(name, not gaps, "; ".join(gaps)) + + +def _verdicts_check(attachments: Mapping[str, str]) -> Check: + """Validation ended with every Check passed and the dry-run not failed.""" + name = "every_check_passes" + text = attachments.get(VERDICTS_FILE) + if text is None: + return Check(name, False, f"no {VERDICTS_FILE}") + outcome = validation_outcome(text) + open_checks = [f"{item['check']} failed" for item in outcome["failed"]] + [ + f"{item['check']} not verifiable" for item in outcome["not_verifiable"] + ] + if outcome["dry_run"].get("verdict") == "fail": + open_checks.append("dry-run failed") + if not outcome["passed"] and not open_checks: + open_checks.append("no verdicts") + return Check(name, not open_checks, "; ".join(open_checks)) + + +def _diagram_matches_graph(attachments: Mapping[str, str]) -> Check: + name = "diagram_matches_graph" + try: + graph = parse_graph(attachments.get(GRAPH_ATTACHMENT, "")) + except GraphError as exc: + return Check(name, False, exc.problems[0]) + matches = attachments.get(DIAGRAM_ATTACHMENT) == render_mermaid(graph) + return Check(name, matches, "" if matches else "the diagram is not the graph's") + + +def _asks_before_submitting(timeline: Sequence[Mapping[str, Any]]) -> Check: + """In an interactive Execution every Specialist confirms with the user before its + first submission (spec risk D32).""" + asked: set[str] = set() + silent: list[str] = [] + seen: set[str] = set() + for run in timeline: + deliverable = run.get("deliverable") + if not deliverable: + continue + if run.get("outcome") == "NeedsInput": + asked.add(deliverable) + elif run.get("outcome") == "Submitted" and deliverable not in seen: + seen.add(deliverable) + if deliverable not in asked: + silent.append(deliverable) + return Check( + "specialists_ask_before_submitting", + bool(seen) and not silent, + "submitted without asking: " + ", ".join(silent) if silent else "", + ) + + +async def _checklist_coverage( + judge: Judge, recommendations: str, checklists: Mapping[str, Sequence[str]] +) -> Check: + name = "pillar_checklists_covered" + questions = { + f"{pillar}.{index}": { + "kind": "yes_no", + "text": f"Do the recommendations address this {pillar} checklist item, " + f"either by recommending it or by explaining why it does not apply? {item}", + } + for pillar, items in checklists.items() + for index, item in enumerate(items) + } + if not recommendations or not questions: + return Check(name, False, "no design recommendations or no checklists") + scores = await judge.answer(recommendations, questions) + per_pillar = { + pillar: sum(scores.get(f"{pillar}.{i}", 0) for i in range(len(items))) + / len(items) + for pillar, items in checklists.items() + if items + } + weakest = min(per_pillar.values()) + detail = ", ".join(f"{pillar} {share:.0%}" for pillar, share in per_pillar.items()) + return Check(name, weakest >= CHECKLIST_COVERAGE, detail) + + +async def _quality(judge: Judge, recommendations: str) -> Check: + name = "recommendations_quality" + if not recommendations: + return Check(name, False, "no design recommendations") + scores = await judge.answer( + recommendations, + {key: {"kind": "graded", "text": text} for key, text in QUALITY_RUBRIC.items()}, + ) + mean = sum(scores.values()) / len(QUALITY_RUBRIC) + detail = ", ".join(f"{key} {scores.get(key, 0):.2f}" for key in QUALITY_RUBRIC) + return Check(name, mean >= QUALITY_BAR, f"mean {mean:.2f}: {detail}") diff --git a/eval/solution_eval.py b/eval/solution_eval.py index 536930e..c014da3 100644 --- a/eval/solution_eval.py +++ b/eval/solution_eval.py @@ -6,7 +6,12 @@ eval/scoring.py. Costs model usage: run deliberately. Usage: GOOGLE_GENAI_USE_VERTEXAI=true GOOGLE_CLOUD_PROJECT= GOOGLE_CLOUD_LOCATION=global \ - .venv/bin/python -m eval.solution_eval [case-id ...] + .venv/bin/python -m eval.solution_eval [--judge] [case-id ...] + +--judge adds the judged checks (pillar checklist coverage, recommendation quality), +using the provider bundle's default model unless EVAL_JUDGE_MODEL names another. +A case marked "interactive" runs with a scripted user in the loop. The exit code is +non-zero when a case fails or exceeds one of its thresholds. """ from __future__ import annotations @@ -14,6 +19,7 @@ from __future__ import annotations import asyncio import json import logging +import os import sys import time from collections import Counter @@ -24,18 +30,25 @@ from pathlib import Path from typing import Any from app.adk.runtime import AgentRuntime, AgentTask, Outcome, RoleSpec, ToolSpec -from app.agent import open_assembly +from app.agent import ExecutionEngine, Interaction, open_assembly from app.config import Settings, get_settings +from app.nodes.execution_nodes import automatic_reply from app.recorder import InMemoryRecorder +from app.states.execution_state import execution_dir from app.tools.local import TerraformRunner +from eval.judge import GeminiJudge, Judge from eval.scoring import ( CaseResult, CaseSpec, + checklist_items, load_cases, + regressions, score_execution, template_headings, ) +GEMINI_PREFIX = "gemini/" +MAX_USER_TURNS = 80 # an interactive case stops being answered after this many prompts ROOT = Path(__file__).resolve().parent CASES_PATH = ROOT / "datasets" / "solution_cases.json" RESULTS_DIR = ROOT / "results" @@ -96,7 +109,33 @@ def token_report(usage: dict[tuple[str, str], Any]) -> dict[str, Any]: } -async def run_case(case: CaseSpec, settings: Settings, run_dir: Path) -> CaseResult: +async def run_with_scripted_user( + engine: ExecutionEngine, + case: CaseSpec, + execution_id: str, + max_user_turns: int = MAX_USER_TURNS, +) -> Interaction: + """Run an interactive Execution, answering each prompt as the case scripts it: + Approvals are granted, cloud reads denied, and questions answered by pattern.""" + interaction = await engine.start( + case.workflow_request, + customer_case=case.id, + allow_cloud_read=False, + execution_id=execution_id, + ) + for _ in range(max_user_turns): + if interaction.status != "awaiting_user" or interaction.prompt is None: + break + reply = automatic_reply( + interaction.prompt, [list(pair) for pair in case.scripted_answers] + ) + interaction = await engine.resume(execution_id, reply) + return interaction + + +async def run_case( + case: CaseSpec, settings: Settings, run_dir: Path, judge: Judge | None = None +) -> CaseResult: from app.adk.adk_runtime import AdkAgentRuntime from app.providers import load_provider @@ -111,48 +150,84 @@ async def run_case(case: CaseSpec, settings: Settings, run_dir: Path) -> CaseRes async with open_assembly( settings, runtime=runtime, recorder=recorder, output_root=run_dir ) as assembly: - interaction = await assembly.engine.start( - case.workflow_request, - pre_approved=True, - allow_cloud_read=False, - execution_id=f"{case.id}-{datetime.now(UTC):%H%M%S}", - scripted_answers=case.scripted_answers, - ) + execution_id = f"{case.id}-{datetime.now(UTC):%H%M%S}" + if case.interactive: + interaction = await run_with_scripted_user( + assembly.engine, case, execution_id + ) + else: + interaction = await assembly.engine.start( + case.workflow_request, + customer_case=case.id, + pre_approved=True, + allow_cloud_read=False, + execution_id=execution_id, + scripted_answers=case.scripted_answers, + ) elapsed = time.monotonic() - started runner = TerraformRunner( binary=settings.TERRAFORM_BINARY, timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS, - plugin_cache_dir=settings.TF_PLUGIN_CACHE_DIR, + plugin_cache_dir=settings.terraform_plugin_cache(), ) result = await score_execution( - case, interaction, template_headings(bundle.output_template), runner.validate + case, + interaction, + template_headings(bundle.output_template), + runner.validate, + judge=judge, + pillar_checklists={ + pillar: checklist_items(bundle.skills[skill].path / "SKILL.md") + for pillar, skill in bundle.pillar_skills.items() + }, + timeline=runtime.timeline, ) ledger = interaction.state.get("ledger", {}) + tokens = token_report(adk_runtime.usage) + revisions = { + kind: item["revisions"] + for kind, item in ledger.get("deliverables", {}).items() + if item["revisions"] + } details = { "execution_id": interaction.execution_id, + "interactive": case.interactive, + "regressions": regressions( + case, + { + "revisions": sum(revisions.values()), + "seconds": elapsed, + "tokens": tokens["total"].get("total"), + }, + ), "seconds": round(elapsed, 1), "first_pass_seconds": first_pass_seconds(runtime.timeline), "orchestrator_turns": interaction.state.get("turns"), - "tokens": token_report(adk_runtime.usage), + "tokens": tokens, "timeline": runtime.timeline, "agent_runs": dict(runtime.runs), "outcomes": dict(runtime.outcomes), - "revisions": { - kind: item["revisions"] - for kind, item in ledger.get("deliverables", {}).items() - if item["revisions"] - }, + "revisions": revisions, "warnings": interaction.state.get("warnings", []), "conversation": interaction.state.get("conversation", []), - "output_dir": str( - run_dir / "deliverables" / "executions" / interaction.execution_id - ), + "output_dir": str(execution_dir(run_dir, interaction.execution_id, case.id)), } return CaseResult(result.case_id, result.status, result.checks, details) -async def main(case_ids: Sequence[str]) -> int: +def make_judge(settings: Settings) -> Judge: + from app.providers import load_provider + + model = os.environ.get("EVAL_JUDGE_MODEL") or load_provider( + settings.CLOUD_PROVIDER + ).models.default.removeprefix(GEMINI_PREFIX) + return GeminiJudge(model) + + +async def main(arguments: Sequence[str]) -> int: + use_judge = "--judge" in arguments + case_ids = [argument for argument in arguments if argument != "--judge"] # Progress (Orchestrator turns, Specialist runs, tool calls, Ledger events) at # INFO; everything else, including ADK and HTTP clients, at LOG_LEVEL. logging.basicConfig( @@ -168,11 +243,12 @@ async def main(case_ids: Sequence[str]) -> int: stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ") run_dir = RESULTS_DIR / stamp run_dir.mkdir(parents=True, exist_ok=True) + judge = make_judge(settings) if use_judge else None results: list[dict[str, Any]] = [] for case in cases: print(f"== {case.id}: running", flush=True) try: - result = await run_case(case, settings, run_dir) + result = await run_case(case, settings, run_dir, judge) except Exception as exc: # noqa: BLE001 - record the failure and continue print(f" ERROR {type(exc).__name__}: {exc}", flush=True) results.append( @@ -192,6 +268,8 @@ async def main(case_ids: Sequence[str]) -> int: f"revisions {details['revisions'] or 'none'}", flush=True, ) + for regression in details["regressions"]: + print(f" REGRESSION {regression}", flush=True) for model, counts in details["tokens"]["by_model"].items(): print(f" tokens {model}: {counts}", flush=True) print(f" tokens total: {details['tokens']['total']}", flush=True) @@ -209,8 +287,12 @@ async def main(case_ids: Sequence[str]) -> int: report = run_dir / "report.json" report.write_text(json.dumps(results, indent=2, default=str), encoding="utf-8") passed = sum(1 for r in results if r.get("passed")) - print(f"\n{passed}/{len(results)} cases passed. Report: {report}") - return 0 if passed == len(results) else 1 + regressed = sum(1 for r in results if r.get("details", {}).get("regressions")) + print( + f"\n{passed}/{len(results)} cases passed, {regressed} regressed. " + f"Report: {report}" + ) + return 0 if passed == len(results) and not regressed else 1 if __name__ == "__main__": diff --git a/providers/gcp.yaml b/providers/gcp.yaml index dd485b0..ca2e482 100644 --- a/providers/gcp.yaml +++ b/providers/gcp.yaml @@ -18,20 +18,21 @@ models: orchestrator: gemini/gemini-3.1-pro-preview product-selector: gemini/gemini-3.1-pro-preview design-advisor: gemini/gemini-3.1-pro-preview + target-architect: gemini/gemini-3.1-pro-preview iac-author: gemini/gemini-3.1-pro-preview validator: gemini/gemini-3.1-pro-preview # Skills each role may load. Role files stay provider-neutral; the bundle names Skills. role_skills: orchestrator: [google-cloud-solution-architecture] - requirements-analyst: [google-cloud-solution-architecture, cloud-discovery] - decomposer: [google-cloud-solution-architecture] - product-selector: [google-cloud-solution-architecture] - diagrammer: [google-cloud-solution-architecture] + requirements-analyst: [google-cloud-solution-architecture, requirements-chain, cloud-discovery] + decomposer: [google-cloud-solution-architecture, requirements-chain] + product-selector: [google-cloud-solution-architecture, requirements-chain] + design-advisor: [google-cloud-solution-architecture, requirements-chain] + target-architect: [google-cloud-solution-architecture, requirements-chain] describer: [google-cloud-solution-architecture] - design-advisor: [google-cloud-solution-architecture] - iac-author: [google-cloud-solution-architecture, iac-validation] - validator: [google-cloud-solution-architecture, iac-validation] + iac-author: [google-cloud-solution-architecture, requirements-chain, iac-validation] + validator: [google-cloud-solution-architecture, requirements-chain, iac-validation] packager: [google-cloud-solution-architecture] # One advisor per architecture-framework pillar; each loads only its pillar's Skill. @@ -157,5 +158,6 @@ role_mcp_servers: product-selector: [developer_knowledge] describer: [developer_knowledge] design-advisor: [developer_knowledge] + target-architect: [developer_knowledge] pillar-advisor: [developer_knowledge] validator: [iam, network_intelligence] diff --git a/scripts/validate_artifacts.py b/scripts/validate_artifacts.py deleted file mode 100644 index a5a883c..0000000 --- a/scripts/validate_artifacts.py +++ /dev/null @@ -1,62 +0,0 @@ -#!/usr/bin/env python3 -"""Offline checks for the architecture package; no cloud calls or provisioning.""" - -import re -import sys -from pathlib import Path - -root = Path(__file__).parents[1] - - -def get_file_path(filename): - search_dirs = [ - root / "deliverables" / "as-is", - root / "deliverables" / "target", - root / "deliverables" / "validation", - root / "deliverables" / "guides", - root / "deliverables", - root / "docs", - root, - ] - for d in search_dirs: - candidate = d / filename - if candidate.is_file(): - return candidate - return root / "deliverables" / "guides" / filename - - -required_files = [ - get_file_path("requirements.md"), - get_file_path("architecture.md"), - get_file_path("architecture.mmd"), - get_file_path("solution-architecture-guide.md"), - root / "terraform" / "main.tf", - root / "terraform" / "variables.tf", -] - -missing = [str(p.relative_to(root)) for p in required_files if not p.is_file()] - -guide_path = get_file_path("solution-architecture-guide.md") -if guide_path.is_file(): - text = guide_path.read_text(encoding="utf-8") - checks = [ - "Functional requirements", - "Selected products", - "Validation results", - "Terraform", - "Mermaid", - ] - missing += [f"guide section: {x}" for x in checks if x not in text] -else: - missing.append("solution-architecture-guide.md") - -mmd_path = get_file_path("architecture.mmd") -if mmd_path.is_file() and not re.search( - r"flowchart|graph", mmd_path.read_text(encoding="utf-8") -): - missing.append("Mermaid graph") - -if missing: - print("FAIL: " + ", ".join(missing)) - sys.exit(1) -print("PASS: required architecture artifacts and guide sections are present") diff --git a/skills/iac-validation/SKILL.md b/skills/iac-validation/SKILL.md index 4507e6d..da7d66a 100644 --- a/skills/iac-validation/SKILL.md +++ b/skills/iac-validation/SKILL.md @@ -36,4 +36,8 @@ Every check runs on a scratch copy of the files you pass. Nothing is applied, an terraform plan -lock=false -var-file= ``` +## Reporting verdicts + +Give a verdict on every Check in the Target architecture and attach them as `verdicts.json`, in the format the requirements-chain Skill gives. The dry-run's result goes in its `dry_run` entry: `pass` when `terraform_validate` passes, `fail` with the error when it does not, and `not_run` when the tool could not run. + Never suggest `terraform apply` as part of validation. diff --git a/skills/requirements-chain/SKILL.md b/skills/requirements-chain/SKILL.md new file mode 100644 index 0000000..30f7e07 --- /dev/null +++ b/skills/requirements-chain/SKILL.md @@ -0,0 +1,122 @@ +--- +name: requirements-chain +description: >- + Defines the data files that carry requirements through to code and validation: + requirements, components, products, recommendations, the Target architecture + graph, the implementation map and the verdicts. Use when producing or checking + any Deliverable of a solution-architecture Execution, to write its data file + in the right format and keep every id traceable. +metadata: + scope: every Deliverable +--- + +# Requirements chain + +Every requirement must be traceable, by id, to the components that serve it, to the Elements and Checks that realise it, to the code that implements them, and to a validation verdict. Each Deliverable attaches one data file that carries its part of that chain. A submission is refused when a link is missing, and the refusal names it. + +Ids are short and stable: reuse an id exactly as the earlier Deliverable wrote it, and never renumber. + +## The files + +### `requirements.json` (requirements) + +A list. Number functional requirements `FR-1`, `FR-2` and non-functional ones `NFR-1`, `NFR-2`. + +```json +[ + {"id": "FR-1", "kind": "functional", "text": "Accept signed webhooks over HTTPS."}, + {"id": "NFR-1", "kind": "non_functional", "text": "Raw events are retained for 30 days."} +] +``` + +`kind` is `functional` or `non_functional`. Write one requirement per entry, so each can be checked on its own. + +### `components.json` (technical decomposition) + +A list of components and the requirement ids each serves. Every functional requirement must be served by at least one component. + +```json +[{"id": "C-1", "name": "Ingest endpoint", "requirements": ["FR-1"]}] +``` + +### `products.json` (product selection) + +One entry per component, naming the product selected for it. + +```json +[{"component": "C-1", "product": "Cloud Run"}] +``` + +### `recommendations.json` (design recommendations) + +A list. Each recommendation names its pillar and the components it applies to; use an empty list for one that applies to the whole workload. + +```json +[{"id": "DR-1", "pillar": "security", "text": "Encrypt the topic with a customer-managed key.", "components": ["C-2"]}] +``` + +Write one configurable decision per recommendation. "Harden the service" cannot become a Check; "disable public ingress on the worker service" can. + +### `target-architecture.json` (Target architecture) + +```json +{ + "elements": [ + {"id": "E-1", "name": "Ingest service", "component": "C-1", "product": "Cloud Run", "resource_type": "google_cloud_run_v2_service"}, + {"id": "E-2", "name": "Ingest identity", "product": "IAM", "resource_type": "google_service_account"} + ], + "relationships": [ + {"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"} + ], + "checks": [ + {"id": "K-1", "applies_to": "E-1", "statement": "ingress is INGRESS_TRAFFIC_ALL and roles/run.invoker is granted to allUsers", "source": "FR-1"}, + {"id": "K-2", "applies_to": "E-2", "statement": "the account is attached to E-1 only", "source": "DR-3"} + ], + "not_applicable": [ + {"recommendation": "DR-9", "reason": "Single region by requirement NFR-2."} + ] +} +``` + +- **Elements.** One per resource to be created. `component` is the component it realises; leave it out for a supporting Element such as an identity, a key or a network. `product` for a component's Element is exactly the product selected for that component. +- **Relationships.** `from` and `to` are Element ids. `kind` says what the connection is: calls, publishes to, reads from, runs as, is granted access to. +- **Checks.** `applies_to` is an Element or Relationship id. `source` is the requirement or recommendation id the Check comes from. Every Element has at least one Check. +- **Completeness.** Every component has an Element. Every non-functional requirement and every recommendation is the `source` of at least one Check, unless the recommendation is listed under `not_applicable` with a reason. Every selected product appears on its component's Element. + +#### Writing a Check + +A Check is a statement that is true or false of the infrastructure code. Name the argument and the value. + +- Verifiable: "`kms_key_name` is set on the topic", "`min_instance_count` is at least 2", "the subscription has a `dead_letter_policy` pointing at E-6". +- Not verifiable: "the service is secure", "follows least privilege", "scales well". + +Split a broad recommendation into several Checks, one per setting. A Check that the validator cannot verify from the code is sent back to you. + +### `implementation.json` (deployment guidance) + +One entry per Check in the Target architecture, saying where the code satisfies it. `file` is an attached file; `address` is the resource address and argument. + +```json +[{"check": "K-1", "file": "terraform/main.tf", "address": "google_cloud_run_v2_service.ingest.ingress"}] +``` + +Implement every Element, Relationship and Check, and nothing the Target architecture does not ask for. When you believe the Target architecture is wrong or incomplete, say so with `needs_input`; do not quietly build something else. + +### `verdicts.json` (validation results) + +```json +{ + "dry_run": {"verdict": "pass", "evidence": "terraform validate: Success! The configuration is valid."}, + "checks": [ + {"check": "K-1", "verdict": "pass", "evidence": "main.tf: ingress = \"INGRESS_TRAFFIC_ALL\"; google_cloud_run_v2_service_iam_member.public"}, + {"check": "K-2", "verdict": "fail", "evidence": "google_service_account.ingest is also attached to the worker service"} + ], + "proposed_additions": [ + {"statement": "the bucket has a retention_policy of 30 days", "applies_to": "E-5", "reason": "NFR-1 has no Check on retention"} + ] +} +``` + +- Give every Check exactly one verdict: `pass`, `fail` or `not_verifiable`, with the evidence you read in the code. +- `dry_run.verdict` is `pass`, `fail`, or `not_run` when the tool could not run. +- Judge the code against the Checks and nothing else. Something the Target architecture lacks is a `proposed_additions` entry, with the requirement or recommendation id it serves in `reason`. It is never a failed Check. diff --git a/tests/a2a/test_server.py b/tests/a2a/test_server.py index 4b6297d..2d4d64b 100644 --- a/tests/a2a/test_server.py +++ b/tests/a2a/test_server.py @@ -8,7 +8,7 @@ import pytest from langgraph.checkpoint.memory import InMemorySaver from starlette.testclient import TestClient -from app.adk.fake_runtime import Call, FakeAgentRuntime +from app.adk.fake_runtime import Call, FakeAgentRuntime, sample_submission from app.adk.roles import load_roles from app.agent import Assembly, ExecutionEngine from app.config import get_settings @@ -32,17 +32,7 @@ LEGACY_GENERATE_KEYS = { def submission(kind: DeliverableKind) -> list[Call]: - spec = DEPENDENCY_GRAPH[kind] - body = "\n".join(f"## {section}\nDetails." for section in spec.sections) - return [ - Call( - "submit_deliverable", - { - "content": f"# {kind}\n{body}\n", - "attachments": {name: f"# {name}\n" for name in spec.attachments}, - }, - ) - ] + return [sample_submission(kind)] def complete_run_turns() -> dict: @@ -57,9 +47,16 @@ def complete_run_turns() -> dict: [delegate(K.REQUIREMENTS)], [delegate(K.TECHNICAL_DECOMPOSITION)], [approve(PhaseId.REQUIREMENTS_DISCOVERY), delegate(K.PRODUCT_SELECTION)], - [delegate(K.ARCHITECTURE_DIAGRAM, K.DESIGN_RECOMMENDATIONS)], - [delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE)], - [approve(PhaseId.SOLUTION_ARCHITECTURE), delegate(K.VALIDATION_RESULTS)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [delegate(K.TARGET_ARCHITECTURE)], + [ + approve(PhaseId.SOLUTION_ARCHITECTURE), + delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE), + ], + [ + approve(PhaseId.SOLUTION_IMPLEMENTATION), + delegate(K.VALIDATION_RESULTS), + ], [approve(PhaseId.SOLUTION_VALIDATION), delegate(K.SOLUTION_GUIDE)], [approve(PhaseId.PACKAGING), Call("finish")], ], @@ -272,7 +269,14 @@ def test_generate_runs_pre_approved_and_keeps_the_legacy_response_keys(tmp_path) assert body["artifacts"]["terraform_code"] == "# terraform/main.tf\n" assert body["artifacts"]["source_discovery_doc"] == "Details." assert "google-cloud-solution-architecture" in body["active_skills"] - assert (tmp_path / "deliverables" / "executions" / body["execution_id"]).is_dir() + assert ( + tmp_path + / "deliverables" + / "cases" + / "unassigned" + / "executions" + / body["execution_id"] + ).is_dir() @pytest.mark.parametrize("payload", [{}, {"request": " "}]) @@ -291,3 +295,27 @@ def test_health_reports_mcp_discovery_gaps(tmp_path): assert body["status"] == "healthy" assert body["mcp_discovery_gaps"] == {"compute": "API not enabled"} + + +def test_generate_groups_the_execution_under_the_callers_customer_case(tmp_path): + turns = { + "orchestrator": [ + [Call("delegate", {"kinds": ["requirements"]})], + [], + ], + "requirements-analyst": [submission(DeliverableKind.REQUIREMENTS)], + } + client, _ = client_for(tmp_path, turns) + with client: + refused = client.post( + "/generate", json={"request": "Design ingestion", "customer_case": "../x"} + ) + accepted = client.post( + "/generate", + json={"request": "Design ingestion", "customer_case": "acme-webhooks"}, + ) + + assert refused.status_code == 400 + assert "customer_case" in refused.json()["error"] + assert accepted.status_code == 200, accepted.json() + assert (tmp_path / "lessons" / "candidates" / "acme-webhooks").is_dir() diff --git a/tests/agents/test_adk_engine.py b/tests/agents/test_adk_engine.py index 0c0f670..446bd17 100644 --- a/tests/agents/test_adk_engine.py +++ b/tests/agents/test_adk_engine.py @@ -12,6 +12,7 @@ from langgraph.checkpoint.memory import InMemorySaver from pydantic import Field from app.adk.adk_runtime import AdkAgentRuntime +from app.adk.fake_runtime import SAMPLE_DATA from app.adk.roles import load_roles from app.agent import ExecutionEngine from app.providers import load_provider @@ -69,7 +70,16 @@ async def test_engine_runs_role_files_through_adk_with_one_voice(tmp_path): call( "needs_input", questions=["What availability target do you need?"] ), - call("submit_deliverable", content=requirements_markdown()), + call( + "submit_deliverable", + content=requirements_markdown(), + attachments=[ + { + "path": "requirements.json", + "content": SAMPLE_DATA["requirements.json"], + } + ], + ), ] ), } diff --git a/tests/agents/test_roles.py b/tests/agents/test_roles.py index 94b3203..675fa9e 100644 --- a/tests/agents/test_roles.py +++ b/tests/agents/test_roles.py @@ -33,7 +33,12 @@ def test_roles_take_skills_mcp_servers_and_models_from_the_bundle(bundle): assert roles[PILLAR_ADVISOR].skills == () assert roles["product-selector"].mcp_servers == ("developer_knowledge",) assert "asset_inventory" in roles["requirements-analyst"].mcp_servers - assert roles["diagrammer"].model == bundle.models.for_role("diagrammer") + assert roles["describer"].model == bundle.models.default + assert roles["target-architect"].skills == ( + "google-cloud-solution-architecture", + "requirements-chain", + ) + assert roles["target-architect"].mcp_servers == ("developer_knowledge",) assert roles["orchestrator"].model == bundle.models.for_role("orchestrator") assert roles["decomposer"].model == bundle.models.default @@ -41,7 +46,8 @@ def test_roles_take_skills_mcp_servers_and_models_from_the_bundle(bundle): def test_roles_name_only_the_local_tools_they_need(bundle): roles = load_roles(AGENTS_DIR, bundle) - assert roles["diagrammer"].tools == ("mermaid_check",) + assert roles["iac-author"].tools == ("terraform_fmt", "terraform_validate") + assert roles["target-architect"].tools == () assert roles["validator"].tools == ("terraform_validate", "terraform_plan") assert roles["requirements-analyst"].tools == () diff --git a/tests/eval/test_scoring.py b/tests/eval/test_scoring.py index f8bf9f8..603c943 100644 --- a/tests/eval/test_scoring.py +++ b/tests/eval/test_scoring.py @@ -2,8 +2,10 @@ from pathlib import Path +from app.adk.fake_runtime import SAMPLE_DATA from app.adk.runtime import ToolResult from app.agent import Interaction +from app.workflows.target_architecture import parse_graph, render_mermaid from eval.scoring import CaseSpec, score_execution, template_headings TEMPLATE = ( @@ -25,11 +27,18 @@ def guide(headings=HEADINGS) -> str: return "\n".join(f"## {heading}\nContent." for heading in headings) +GRAPH = SAMPLE_DATA["target-architecture.json"] + + def execution(status="completed", **overrides) -> Interaction: deliverables = { "requirements": { "content": "## Functional requirements\nAccept webhooks.\n## Current state\nNone.", - "attachments": {}, + "attachments": {"requirements.json": SAMPLE_DATA["requirements.json"]}, + }, + "technical_decomposition": { + "content": "## Components\nIngress.", + "attachments": {"components.json": SAMPLE_DATA["components.json"]}, }, "product_selection": { "content": ( @@ -39,12 +48,19 @@ def execution(status="completed", **overrides) -> Interaction: "**Pros**: control **Cons**: toil |\n" "| Queue | Pub/Sub | ... | Cloud Tasks | ... |\n| Archive | Cloud Storage | ... |" ), - "attachments": {}, + "attachments": {"products.json": SAMPLE_DATA["products.json"]}, }, - "architecture_diagram": { - "content": "diagram", + "design_recommendations": { + "content": "## Reliability\nUse two zones because NFR-1 asks for 99.9%.", "attachments": { - "architecture.mmd": "flowchart TD\n A[Client] --> B[Run]\n" + "recommendations.json": SAMPLE_DATA["recommendations.json"] + }, + }, + "target_architecture": { + "content": "## Elements\n## Relationships\n## Checks\n", + "attachments": { + "target-architecture.json": GRAPH, + "architecture.mmd": render_mermaid(parse_graph(GRAPH)), }, }, "deployment_guidance": { @@ -52,8 +68,13 @@ def execution(status="completed", **overrides) -> Interaction: "attachments": { "terraform/main.tf": "resource {}", "terraform/variables.tf": "", + "implementation.json": SAMPLE_DATA["implementation.json"], }, }, + "validation_results": { + "content": "## Deployment dry-run\nPass.", + "attachments": {"verdicts.json": SAMPLE_DATA["verdicts.json"]}, + }, "solution_guide": {"content": guide(), "attachments": {}}, } for kind, value in overrides.items(): @@ -148,7 +169,7 @@ async def test_invalid_terraform_and_diagram_fail_and_warnings_fail_completion() result = await score_execution( CASE, - execution("completed_with_warnings", architecture_diagram=diagram), + execution("completed_with_warnings", target_architecture=diagram), HEADINGS, failing_terraform, ) @@ -181,3 +202,276 @@ def test_benchmark_cases_load_with_valid_answer_patterns(): for pattern, answer in case.scripted_answers: re.compile(pattern) assert answer + + +# --- checks that can see quality (iteration 4, step 8) --------------------------------- + + +class FakeJudge: + """Scores every question with a fixed value, or per id from a mapping.""" + + def __init__(self, default=1.0, **by_id): + self.default, self.by_id = default, by_id + self.asked: list[dict] = [] + + async def answer(self, document, questions): + self.asked.append(dict(questions)) + return {key: self.by_id.get(key, self.default) for key in questions} + + +CHECKLISTS = { + "reliability": ["No single point of failure.", "Backups are tested."], + "security": ["Least privilege is applied."], +} + + +def deliverable(content: str, **attachments: str) -> dict: + return {"content": content, "attachments": attachments} + + +async def test_a_requirement_that_reaches_no_check_breaks_the_chain(): + import json + + requirements = json.loads(SAMPLE_DATA["requirements.json"]) + requirements.append({"id": "NFR-2", "kind": "non_functional", "text": "Retain."}) + + result = await score_execution( + CASE, + execution( + requirements=deliverable( + "r", **{"requirements.json": json.dumps(requirements)} + ) + ), + HEADINGS, + passing_terraform, + ) + + chain = check(result, "requirements_chain_complete") + assert not chain.passed + assert chain.detail == "Requirement NFR-2 has no Check" + + +async def test_a_check_left_failed_or_unverifiable_fails_the_case(): + import json + + verdicts = json.loads(SAMPLE_DATA["verdicts.json"]) + verdicts["checks"][0]["verdict"] = "fail" + verdicts["checks"][1]["verdict"] = "not_verifiable" + verdicts["proposed_additions"] = [ + {"statement": "s", "applies_to": "E-1", "reason": "NFR-1"} + ] + + result = await score_execution( + CASE, + execution( + validation_results=deliverable( + "v", **{"verdicts.json": json.dumps(verdicts)} + ) + ), + HEADINGS, + passing_terraform, + ) + + assert ( + check(result, "every_check_passes").detail == "K-1 failed; K-2 not verifiable" + ) + + +async def test_a_diagram_that_is_not_the_graphs_fails(): + drawn = deliverable( + "t", + **{ + "target-architecture.json": GRAPH, + "architecture.mmd": "flowchart LR\n a --> b\n", + }, + ) + + result = await score_execution( + CASE, execution(target_architecture=drawn), HEADINGS, passing_terraform + ) + + assert not check(result, "diagram_matches_graph").passed + assert check(await _complete(), "diagram_matches_graph").passed + + +async def _complete(): + return await score_execution(CASE, execution(), HEADINGS, passing_terraform) + + +async def test_judged_checks_run_only_with_a_judge(): + without = await score_execution(CASE, execution(), HEADINGS, passing_terraform) + judged = await score_execution( + CASE, + execution(), + HEADINGS, + passing_terraform, + judge=FakeJudge(), + pillar_checklists=CHECKLISTS, + ) + + names = {c.name for c in judged.checks} - {c.name for c in without.checks} + assert names == {"pillar_checklists_covered", "recommendations_quality"} + assert judged.score == 1.0 + + +async def test_checklist_coverage_is_judged_per_pillar_and_the_weakest_decides(): + judge = FakeJudge(**{"reliability.1": 0.0}) + + result = await score_execution( + CASE, + execution(), + HEADINGS, + passing_terraform, + judge=judge, + pillar_checklists=CHECKLISTS, + ) + + coverage = check(result, "pillar_checklists_covered") + assert not coverage.passed + assert coverage.detail == "reliability 50%, security 100%" + assert "Backups are tested." in judge.asked[0]["reliability.1"]["text"] + + +async def test_generic_recommendations_fail_the_quality_rubric(): + result = await score_execution( + CASE, + execution(), + HEADINGS, + passing_terraform, + judge=FakeJudge(default=1.0, specific=0.0, actionable=0.33, traceable=0.33), + pillar_checklists=CHECKLISTS, + ) + + quality = check(result, "recommendations_quality") + assert not quality.passed + assert quality.detail.startswith("mean 0.42") + + +async def test_an_interactive_case_checks_specialists_ask_before_submitting(): + from dataclasses import replace + + interactive = replace(CASE, interactive=True) + asked = [ + {"deliverable": "requirements", "outcome": "NeedsInput"}, + {"deliverable": "requirements", "outcome": "Submitted"}, + {"deliverable": None, "outcome": "TurnEnded"}, + ] + silent = [*asked, {"deliverable": "product_selection", "outcome": "Submitted"}] + + good = await score_execution( + interactive, execution(), HEADINGS, passing_terraform, timeline=asked + ) + bad = await score_execution( + interactive, execution(), HEADINGS, passing_terraform, timeline=silent + ) + batch = await score_execution(CASE, execution(), HEADINGS, passing_terraform) + + assert check(good, "specialists_ask_before_submitting").passed + assert ( + check(bad, "specialists_ask_before_submitting").detail + == "submitted without asking: product_selection" + ) + assert "specialists_ask_before_submitting" not in {c.name for c in batch.checks} + + +def test_exceeding_a_threshold_is_a_regression(): + from dataclasses import replace + + from eval.scoring import regressions + + case = replace(CASE, thresholds={"revisions": 2, "seconds": 3000, "tokens": 4e6}) + + assert regressions(case, {"revisions": 2, "seconds": 2999.5, "tokens": 3.9e6}) == [] + assert regressions(case, {"revisions": 3, "seconds": 3100, "tokens": None}) == [ + "revisions: 3 > 2", + "seconds: 3100 > 3000", + ] + assert regressions(CASE, {"revisions": 9}) == [] + + +def test_every_pillar_skill_yields_checklist_items(): + from app.providers import load_provider + from eval.scoring import checklist_items + + bundle = load_provider("gcp") + + for pillar, skill in bundle.pillar_skills.items(): + items = checklist_items(bundle.skills[skill].path / "SKILL.md") + assert len(items) >= 3, pillar + assert all( + not item.startswith(("-", "*")) and "\n" not in item for item in items + ) + + +def test_a_judge_reply_is_parsed_defensively(): + from eval.judge import parse_scores + + questions = {"a": {}, "b": {}, "c": {}, "d": {}} + + assert parse_scores('{"a": 1, "b": 0.33, "c": true, "d": 7}', questions) == { + "a": 1.0, + "b": 0.33, + "c": 1.0, + "d": 1.0, + } + assert parse_scores("not json", questions) == dict.fromkeys(questions, 0.0) + assert parse_scores('{"a": "yes"}', questions)["a"] == 0.0 + + +async def test_a_scripted_user_drives_an_interactive_execution(tmp_path): + from dataclasses import replace + + from langgraph.checkpoint.memory import InMemorySaver + + from app.adk.fake_runtime import Call, FakeAgentRuntime, sample_submission + from app.adk.runtime import RoleSpec + from app.agent import ExecutionEngine + from app.recorder import InMemoryRecorder + from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind + from eval.solution_eval import run_with_scripted_user + + requirements = DeliverableKind.REQUIREMENTS + analyst = DEPENDENCY_GRAPH[requirements].specialist + roles = { + "orchestrator": RoleSpec("orchestrator", "", budget=10), + **{ + spec.specialist: RoleSpec(spec.specialist, "", budget=10) + for spec in DEPENDENCY_GRAPH.values() + }, + } + runtime = FakeAgentRuntime( + { + "orchestrator": [ + [Call("delegate", {"kinds": ["requirements"]})], + [Call("ask_user")], + [Call("delegate", {"kinds": ["requirements"]})], + [Call("ask_user", {"questions": ["Which region?"]})], + [Call("ask_user", {"questions": ["Anything else?"]})], + ], + analyst: [ + [Call("needs_input", {"questions": ["Do you approve this draft?"]})], + [sample_submission(requirements)], + ], + } + ) + engine = ExecutionEngine( + runtime=runtime, + roles=roles, + recorder=InMemoryRecorder(), + checkpointer=InMemorySaver(), + output_root=tmp_path, + ) + case = replace( + CASE, + interactive=True, + scripted_answers=(("approve", "Approved."), ("region", "europe-west2.")), + ) + + final = await run_with_scripted_user( + engine, case, "exec-interactive", max_user_turns=2 + ) + + replies = [m["text"] for m in final.state["conversation"] if m["from"] == "user"] + assert any("Approved." in reply for reply in replies) + assert any("europe-west2." in reply for reply in replies) + assert final.state["deliverables"]["requirements"]["content"] diff --git a/tests/execution/test_deliverables.py b/tests/execution/test_deliverables.py index 71846b6..dda0ba8 100644 --- a/tests/execution/test_deliverables.py +++ b/tests/execution/test_deliverables.py @@ -47,6 +47,7 @@ def test_every_phase_groups_at_least_one_deliverable_with_a_distinct_specialist( assert PHASE_ORDER == ( PhaseId.REQUIREMENTS_DISCOVERY, PhaseId.SOLUTION_ARCHITECTURE, + PhaseId.SOLUTION_IMPLEMENTATION, PhaseId.SOLUTION_VALIDATION, PhaseId.PACKAGING, ) @@ -56,55 +57,68 @@ def test_every_phase_groups_at_least_one_deliverable_with_a_distinct_specialist( assert len(specialists) == len(set(specialists)) -def test_graph_matches_the_upstream_skill_dependencies(): +def test_the_target_architecture_sits_between_the_design_and_the_code(): depends = {kind: set(spec.depends_on) for kind, spec in DEPENDENCY_GRAPH.items()} K = DeliverableKind assert depends[K.REQUIREMENTS] == set() assert depends[K.TECHNICAL_DECOMPOSITION] == {K.REQUIREMENTS} assert depends[K.PRODUCT_SELECTION] == {K.TECHNICAL_DECOMPOSITION} - assert depends[K.ARCHITECTURE_DIAGRAM] == {K.PRODUCT_SELECTION} - assert depends[K.ARCHITECTURE_DESCRIPTION] == { - K.ARCHITECTURE_DIAGRAM, - K.PRODUCT_SELECTION, - } assert depends[K.DESIGN_RECOMMENDATIONS] == {K.PRODUCT_SELECTION, K.REQUIREMENTS} - assert depends[K.DEPLOYMENT_GUIDANCE] == { + assert depends[K.TARGET_ARCHITECTURE] == { K.PRODUCT_SELECTION, K.DESIGN_RECOMMENDATIONS, } + # Everything after the graph is derived from it. + assert depends[K.ARCHITECTURE_DESCRIPTION] == {K.TARGET_ARCHITECTURE} + assert depends[K.DEPLOYMENT_GUIDANCE] == {K.TARGET_ARCHITECTURE} assert depends[K.VALIDATION_RESULTS] == {K.DEPLOYMENT_GUIDANCE} assert depends[K.SOLUTION_GUIDE] == set( deliverables_in(PhaseId.SOLUTION_VALIDATION) ) +def test_the_design_is_approved_before_code_is_written(): + design = PhaseId.SOLUTION_ARCHITECTURE + implementation = PhaseId.SOLUTION_IMPLEMENTATION + + assert DEPENDENCY_GRAPH[DeliverableKind.TARGET_ARCHITECTURE].phase is design + assert DEPENDENCY_GRAPH[DeliverableKind.DEPLOYMENT_GUIDANCE].phase is implementation + assert PHASE_ORDER.index(design) < PHASE_ORDER.index(implementation) + + def test_inputs_are_earlier_phases_plus_indirect_dependencies_in_graph_order(): - assert inputs_of(DeliverableKind.REQUIREMENTS) == () - assert inputs_of(DeliverableKind.DEPLOYMENT_GUIDANCE) == ( + design = ( DeliverableKind.REQUIREMENTS, DeliverableKind.TECHNICAL_DECOMPOSITION, DeliverableKind.PRODUCT_SELECTION, DeliverableKind.DESIGN_RECOMMENDATIONS, + DeliverableKind.TARGET_ARCHITECTURE, ) - assert inputs_of(DeliverableKind.ARCHITECTURE_DESCRIPTION) == ( - DeliverableKind.REQUIREMENTS, - DeliverableKind.TECHNICAL_DECOMPOSITION, - DeliverableKind.PRODUCT_SELECTION, - DeliverableKind.ARCHITECTURE_DIAGRAM, - ) + assert inputs_of(DeliverableKind.REQUIREMENTS) == () + assert inputs_of(DeliverableKind.DEPLOYMENT_GUIDANCE) == design + assert inputs_of(DeliverableKind.ARCHITECTURE_DESCRIPTION) == design + assert inputs_of(DeliverableKind.TARGET_ARCHITECTURE) == design[:4] assert set(inputs_of(DeliverableKind.SOLUTION_GUIDE)) == set(DeliverableKind) - { DeliverableKind.SOLUTION_GUIDE } +def sections_missing(kind: DeliverableKind, content: str) -> list[str]: + return [m for m in check_submission(kind, content, {}) if m.startswith("section:")] + + def test_submission_meeting_the_contract_has_nothing_missing(): content = ( "# Deployment guidance\n" "## 6.1. Deployment prerequisites\nEnable APIs.\n" "## 6.2. Step-by-step deployment instructions\nRun terraform.\n" ) - attachments = {"terraform/main.tf": "resource {}", "terraform/variables.tf": ""} + attachments = { + "terraform/main.tf": "resource {}", + "terraform/variables.tf": "variable {}", + "implementation.json": "[]", + } assert ( check_submission(DeliverableKind.DEPLOYMENT_GUIDANCE, content, attachments) @@ -122,6 +136,7 @@ def test_submission_reports_missing_sections_and_attachments(): assert missing == ( "section: Step-by-step deployment instructions", "attachment: terraform/variables.tf", + "attachment: implementation.json", ) @@ -143,7 +158,7 @@ def test_section_matching_ignores_numbering_case_and_trailing_punctuation(headin "## Sustainability\n" ) - assert check_submission(DeliverableKind.DESIGN_RECOMMENDATIONS, content, {}) == () + assert sections_missing(DeliverableKind.DESIGN_RECOMMENDATIONS, content) == [] def test_section_matches_a_provider_prefixed_heading_but_not_a_longer_word(): @@ -152,7 +167,7 @@ def test_section_matches_a_provider_prefixed_heading_but_not_a_longer_word(): "## Non-functional requirements\n" ) - assert check_submission(DeliverableKind.PRODUCT_SELECTION, content, {}) == () + assert sections_missing(DeliverableKind.PRODUCT_SELECTION, content) == [] assert "section: Functional requirements" in check_submission( DeliverableKind.REQUIREMENTS, content, {} ) @@ -173,3 +188,32 @@ def test_empty_content_is_refused(): assert check_submission(DeliverableKind.TECHNICAL_DECOMPOSITION, " \n", {}) == ( "content: must not be empty", ) + + +# --- contracts beyond headings --------------------------------------------------------- + + +def test_architecture_description_needs_component_and_flow_sections(): + missing = check_submission( + DeliverableKind.ARCHITECTURE_DESCRIPTION, "The system works.", {} + ) + + assert missing == ("section: Components", "section: Flow") + assert ( + check_submission( + DeliverableKind.ARCHITECTURE_DESCRIPTION, + "## Architecture components\nA.\n## Data flow\nB.\n", + {}, + ) + == () + ) + + +def test_a_required_attachment_must_have_content(): + missing = check_submission( + DeliverableKind.VALIDATION_RESULTS, + "## Deployment dry-run\nPass.\n## Architecture and policy analysis\nPass.\n", + {"verdicts.json": " \n"}, + ) + + assert missing == ("attachment: verdicts.json must not be empty",) diff --git a/tests/execution/test_engine.py b/tests/execution/test_engine.py index bf09ab1..98bb1cc 100644 --- a/tests/execution/test_engine.py +++ b/tests/execution/test_engine.py @@ -3,13 +3,14 @@ Driven entirely through ExecutionEngine.start/resume with a scripted agent runtime. """ +import json from pathlib import Path import pytest from langgraph.checkpoint.memory import InMemorySaver from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver -from app.adk.fake_runtime import Call, FakeAgentRuntime +from app.adk.fake_runtime import Call, FakeAgentRuntime, sample_submission from app.adk.runtime import RoleSpec, ToolResult, ToolSpec from app.agent import ExecutionEngine from app.recorder import InMemoryRecorder @@ -50,12 +51,7 @@ def reopen(kind: DeliverableKind, reason: str) -> Call: FINISH = Call("finish") -def submission(kind: DeliverableKind, note: str = "") -> Call: - spec = DEPENDENCY_GRAPH[kind] - body = "\n".join(f"## {section}\n{note or 'Details.'}" for section in spec.sections) - content = f"# {kind}\n{note or 'Summary.'}\n{body}\n" - attachments = {name: f"# {name}\n" for name in spec.attachments} - return Call("submit_deliverable", {"content": content, "attachments": attachments}) +submission = sample_submission def submits(kind: DeliverableKind) -> list[Call]: @@ -84,9 +80,16 @@ def happy_path_turns(**extra_specialist_turns) -> dict: [delegate(K.REQUIREMENTS)], [delegate(K.TECHNICAL_DECOMPOSITION)], [request_approval(P.REQUIREMENTS_DISCOVERY), delegate(K.PRODUCT_SELECTION)], - [delegate(K.ARCHITECTURE_DIAGRAM, K.DESIGN_RECOMMENDATIONS)], - [delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE)], - [request_approval(P.SOLUTION_ARCHITECTURE), delegate(K.VALIDATION_RESULTS)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [delegate(K.TARGET_ARCHITECTURE)], + [ + request_approval(P.SOLUTION_ARCHITECTURE), + delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE), + ], + [ + request_approval(P.SOLUTION_IMPLEMENTATION), + delegate(K.VALIDATION_RESULTS), + ], [request_approval(P.SOLUTION_VALIDATION), delegate(K.SOLUTION_GUIDE)], [request_approval(P.PACKAGING), FINISH], ], @@ -112,7 +115,14 @@ async def test_pre_approved_execution_completes_and_writes_deliverables(tmp_path assert set(ledger["phases"].values()) == {"approved"} assert {d["status"] for d in ledger["deliverables"].values()} == {"submitted"} - out = tmp_path / "deliverables" / "executions" / result.execution_id + out = ( + tmp_path + / "deliverables" + / "cases" + / "unassigned" + / "executions" + / result.execution_id + ) assert (out / "solution-architecture-guide.md").is_file() for kind in K: assert (out / "deliverables" / f"{kind}.md").is_file(), kind @@ -122,7 +132,7 @@ async def test_pre_approved_execution_completes_and_writes_deliverables(tmp_path assert recorder.statuses[result.execution_id][-1]["status"] == "completed" assert {s["kind"] for s in recorder.submissions[result.execution_id]} == set(K) recorded_types = [e.type for e in recorder.events[result.execution_id]] - assert recorded_types.count("approved") == 4 + assert recorded_types.count("approved") == 5 async def test_independent_specialists_run_together_between_orchestrator_turns( @@ -133,12 +143,12 @@ async def test_independent_specialists_run_together_between_orchestrator_turns( await make_engine(tmp_path, runtime).start("Ingestion", pre_approved=True) roles = [run.role for run in runtime.runs] - fourth_turn = [i for i, role in enumerate(roles) if role == "orchestrator"][3] - assert set(roles[fourth_turn + 1 : fourth_turn + 3]) == { - specialist(K.ARCHITECTURE_DIAGRAM), - specialist(K.DESIGN_RECOMMENDATIONS), + sixth_turn = [i for i, role in enumerate(roles) if role == "orchestrator"][5] + assert set(roles[sixth_turn + 1 : sixth_turn + 3]) == { + specialist(K.ARCHITECTURE_DESCRIPTION), + specialist(K.DEPLOYMENT_GUIDANCE), } - assert roles[fourth_turn + 3] == "orchestrator" + assert roles[sixth_turn + 3] == "orchestrator" async def test_specialist_receives_its_dependencies_content(tmp_path): @@ -154,9 +164,13 @@ async def test_specialist_receives_its_dependencies_content(tmp_path): "requirements", "technical_decomposition", "product_selection", - "architecture_diagram", + "design_recommendations", + "target_architecture", ] - assert "architecture.mmd" in dependencies["architecture_diagram"]["attachments"] + # The engine drew the diagram from the graph when the Target architecture was submitted. + assert dependencies["target_architecture"]["attachments"][ + "architecture.mmd" + ].startswith("flowchart") assert describer_run.task.deliverable == "architecture_description" @@ -334,16 +348,17 @@ async def test_requested_changes_lead_to_a_revision_and_a_new_approval(tmp_path) async def test_questions_from_parallel_specialists_reach_the_user_in_one_prompt( tmp_path, ): - def diagrammer_turn(task): + def describer_turn(task): if task.context["answers"]: - return submits(K.ARCHITECTURE_DIAGRAM) - return [Call("needs_input", {"questions": ["Single region or multi-region?"]})] + return submits(K.ARCHITECTURE_DESCRIPTION) + return [Call("needs_input", {"questions": ["Who reads this description?"]})] - def advisor_turn(task): + def iac_turn(task): if task.context["answers"]: - return submits(K.DESIGN_RECOMMENDATIONS) - return [Call("needs_input", {"questions": ["What is the RTO?"]})] + return submits(K.DEPLOYMENT_GUIDANCE) + return [Call("needs_input", {"questions": ["Which region?"]})] + both = delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE) runtime = FakeAgentRuntime( { "orchestrator": [ @@ -351,47 +366,59 @@ async def test_questions_from_parallel_specialists_reach_the_user_in_one_prompt( [delegate(K.TECHNICAL_DECOMPOSITION)], [request_approval(P.REQUIREMENTS_DISCOVERY)], [delegate(K.PRODUCT_SELECTION)], - [delegate(K.ARCHITECTURE_DIAGRAM, K.DESIGN_RECOMMENDATIONS)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [delegate(K.TARGET_ARCHITECTURE)], + [request_approval(P.SOLUTION_ARCHITECTURE)], + [both], [ask_user()], - [delegate(K.ARCHITECTURE_DIAGRAM, K.DESIGN_RECOMMENDATIONS)], + [both], [ask_user("Continue?")], ], - specialist(K.REQUIREMENTS): [submits(K.REQUIREMENTS)], - specialist(K.TECHNICAL_DECOMPOSITION): [submits(K.TECHNICAL_DECOMPOSITION)], - specialist(K.PRODUCT_SELECTION): [submits(K.PRODUCT_SELECTION)], - specialist(K.ARCHITECTURE_DIAGRAM): [diagrammer_turn, diagrammer_turn], - specialist(K.DESIGN_RECOMMENDATIONS): [advisor_turn, advisor_turn], + **{ + specialist(kind): [submits(kind)] + for kind in ( + K.REQUIREMENTS, + K.TECHNICAL_DECOMPOSITION, + K.PRODUCT_SELECTION, + K.DESIGN_RECOMMENDATIONS, + K.TARGET_ARCHITECTURE, + ) + }, + specialist(K.ARCHITECTURE_DESCRIPTION): [describer_turn, describer_turn], + specialist(K.DEPLOYMENT_GUIDANCE): [iac_turn, iac_turn], } ) engine = make_engine(tmp_path, runtime) approval = await engine.start("Ingestion") - first = await engine.resume( + design = await engine.resume( approval.execution_id, {"approval": {"phase": "requirements_discovery", "decision": "approve"}}, ) + first = await engine.resume( + design.execution_id, + {"approval": {"phase": "solution_architecture", "decision": "approve"}}, + ) assert first.prompt == { "questions": [ { - "from": "architecture_diagram", - "question": "Single region or multi-region?", + "from": "architecture_description", + "question": "Who reads this description?", }, - {"from": "design_recommendations", "question": "What is the RTO?"}, + {"from": "deployment_guidance", "question": "Which region?"}, ] } - second = await engine.resume( - first.execution_id, {"reply": "Single region, RTO 1 hour"} - ) + second = await engine.resume(first.execution_id, {"reply": "Engineers, in London"}) deliverables = second.state["ledger"]["deliverables"] - assert deliverables["architecture_diagram"]["status"] == "submitted" - assert deliverables["design_recommendations"]["status"] == "submitted" - advisor_retry = [ - r for r in runtime.runs if r.role == specialist(K.DESIGN_RECOMMENDATIONS) + assert deliverables["architecture_description"]["status"] == "submitted" + assert deliverables["deployment_guidance"]["status"] == "submitted" + iac_retry = [ + r for r in runtime.runs if r.role == specialist(K.DEPLOYMENT_GUIDANCE) ][1] - assert advisor_retry.task.context["answers"] == [ - {"questions": ["What is the RTO?"], "reply": "Single region, RTO 1 hour"} + assert iac_retry.task.context["answers"] == [ + {"questions": ["Which region?"], "reply": "Engineers, in London"} ] @@ -404,14 +431,18 @@ async def test_validation_failure_revises_deployment_guidance_and_reapproves(tmp [delegate(K.REQUIREMENTS)], [delegate(K.TECHNICAL_DECOMPOSITION)], [request_approval(P.REQUIREMENTS_DISCOVERY), delegate(K.PRODUCT_SELECTION)], - [delegate(K.ARCHITECTURE_DIAGRAM, K.DESIGN_RECOMMENDATIONS)], - [delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE)], - [request_approval(P.SOLUTION_ARCHITECTURE), delegate(K.VALIDATION_RESULTS)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [delegate(K.TARGET_ARCHITECTURE)], + [ + request_approval(P.SOLUTION_ARCHITECTURE), + delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE), + ], + [request_approval(P.SOLUTION_IMPLEMENTATION), delegate(K.VALIDATION_RESULTS)], [ reopen(K.DEPLOYMENT_GUIDANCE, "terraform plan: missing IAM binding"), delegate(K.DEPLOYMENT_GUIDANCE), ], - [request_approval(P.SOLUTION_ARCHITECTURE), delegate(K.VALIDATION_RESULTS)], + [request_approval(P.SOLUTION_IMPLEMENTATION), delegate(K.VALIDATION_RESULTS)], [request_approval(P.SOLUTION_VALIDATION), delegate(K.SOLUTION_GUIDE)], [request_approval(P.PACKAGING), FINISH], ] @@ -430,9 +461,10 @@ async def test_validation_failure_revises_deployment_guidance_and_reapproves(tmp assert result.status == "completed" events = result.state["ledger"]["events"] withdrawn = [e["subject"] for e in events if e["type"] == "approval_withdrawn"] - assert withdrawn == ["solution_architecture"] + assert withdrawn == ["solution_implementation"] requests = [e["subject"] for e in events if e["type"] == "approval_requested"] - assert requests.count("solution_architecture") == 2 + assert requests.count("solution_implementation") == 2 + assert requests.count("solution_architecture") == 1 iac_runs = [r for r in runtime.runs if r.role == specialist(K.DEPLOYMENT_GUIDANCE)] assert iac_runs[1].task.context["feedback"] == [ "terraform plan: missing IAM binding" @@ -456,7 +488,12 @@ async def test_pre_approved_escalation_ends_with_warnings(tmp_path): assert result.status == "completed_with_warnings" assert "revision limit" in result.state["warnings"][0] - assert not (tmp_path / "deliverables").exists() + # No Deliverable files are written, but the request stays on record. + case = tmp_path / "deliverables" / "cases" / "unassigned" + assert not (case / "executions").exists() + [intent] = json.loads((case / "intent" / "history.json").read_text())["intents"] + assert intent["status"] == "completed_with_warnings" + assert intent["execution"] is None # --- budgets ------------------------------------------------------------------------------------- @@ -514,7 +551,7 @@ def cloud_read_factory(calls: list[str]): tier="cloud_read", ) - def factory(role: RoleSpec, deliverable: str | None): + def factory(role: RoleSpec, deliverable: str | None, working: dict): return [tool] if role.name == "requirements-analyst" else [] return factory @@ -686,3 +723,249 @@ async def test_pre_approved_questions_use_matching_scripted_answers(tmp_path): assert "No user is available" not in first_reply second_reply = result.state["conversation"][4]["text"] assert second_reply.startswith("No user is available") + + +# --- contract and draft in the Specialist's context (iteration 4, steps 2 and 4) ------- + + +async def test_specialist_context_carries_its_contract(tmp_path): + runtime = FakeAgentRuntime(happy_path_turns()) + + await make_engine(tmp_path, runtime).start("Ingestion", pre_approved=True) + + run = next(r for r in runtime.runs if r.role == specialist(K.VALIDATION_RESULTS)) + assert run.task.context["contract"] == { + "sections": ["Deployment dry-run", "Architecture and policy analysis"], + "attachments": ["verdicts.json"], + } + assert run.task.context["draft"] is None + + +async def test_a_draft_sent_with_questions_comes_back_with_the_answer(tmp_path): + draft = sample_submission(K.REQUIREMENTS, note="Drafted for approval.").args + + def confirm_then_submit_what_came_back(task): + returned = task.context["draft"] + return [Call("submit_deliverable", returned)] + + runtime = FakeAgentRuntime( + { + "orchestrator": [ + [delegate(K.REQUIREMENTS)], + [ask_user()], + [delegate(K.REQUIREMENTS)], + [ask_user("Anything else?")], + ], + specialist(K.REQUIREMENTS): [ + [ + Call( + "needs_input", + { + "questions": ["Do you approve this draft?"], + "draft": draft["content"], + "attachments": [ + {"path": path, "content": content} + for path, content in draft["attachments"].items() + ], + }, + ) + ], + confirm_then_submit_what_came_back, + ], + } + ) + engine = make_engine(tmp_path, runtime) + + paused = await engine.start("Ingestion") + assert paused.state["drafts"]["requirements"]["content"] == draft["content"] + + after = await engine.resume(paused.execution_id, {"reply": "Approved."}) + + second_run = [r for r in runtime.runs if r.role == specialist(K.REQUIREMENTS)][1] + assert second_run.task.context["draft"] == { + "content": draft["content"], + "attachments": draft["attachments"], + } + assert second_run.task.context["answers"][-1]["reply"] == "Approved." + assert after.state["deliverables"]["requirements"]["content"] == draft["content"] + assert after.state["drafts"] == {} + + +# --- cap on parallel Specialists (iteration 4, step 5) --------------------------------- + + +async def test_parallel_specialists_never_exceed_the_cap(tmp_path): + import asyncio + + from app.adk.runtime import RunLimiter + + in_flight = 0 + peak = 0 + + class SlowRuntime(FakeAgentRuntime): + async def run(self, role, task, tools): + nonlocal in_flight, peak + if role.name == "orchestrator": + return await super().run(role, task, tools) + in_flight += 1 + peak = max(peak, in_flight) + await asyncio.sleep(0.01) + try: + return await super().run(role, task, tools) + finally: + in_flight -= 1 + + runtime = SlowRuntime(happy_path_turns()) + engine = make_engine(tmp_path, runtime, limiter=RunLimiter(1)) + + result = await engine.start("Ingestion", pre_approved=True) + + assert result.status == "completed" + assert peak == 1 + + +async def test_without_a_cap_independent_specialists_overlap(tmp_path): + import asyncio + + in_flight = 0 + peak = 0 + + class SlowRuntime(FakeAgentRuntime): + async def run(self, role, task, tools): + nonlocal in_flight, peak + if role.name == "orchestrator": + return await super().run(role, task, tools) + in_flight += 1 + peak = max(peak, in_flight) + await asyncio.sleep(0.01) + try: + return await super().run(role, task, tools) + finally: + in_flight -= 1 + + runtime = SlowRuntime(happy_path_turns()) + + await make_engine(tmp_path, runtime).start("Ingestion", pre_approved=True) + + assert peak == 2 + + +# --- Customer cases group Executions --------------------------------------------------- + + +async def test_an_execution_in_a_customer_case_writes_under_that_case(tmp_path): + recorder = InMemoryRecorder() + engine = make_engine( + tmp_path, FakeAgentRuntime(happy_path_turns()), recorder=recorder + ) + + result = await engine.start( + "Ingestion", pre_approved=True, customer_case="acme-webhooks" + ) + + case_dir = tmp_path / "deliverables" / "cases" / "acme-webhooks" + out = case_dir / "executions" / result.execution_id + assert (out / "solution-architecture-guide.md").is_file() + assert result.state["customer_case"] == "acme-webhooks" + + manifest = json.loads((out / "execution.json").read_text(encoding="utf-8")) + assert manifest["customer_case"] == "acme-webhooks" + assert manifest["workflow_request"] == "Ingestion" + assert manifest["intent_version"] == 1 + assert manifest["solution_guide"] == "solution-architecture-guide.md" + assert manifest["deliverables"]["deployment_guidance"] == { + "document": "deliverables/deployment_guidance.md", + "attachments": [ + "implementation.json", + "terraform/main.tf", + "terraform/variables.tf", + ], + } + for entry in manifest["deliverables"].values(): + assert (out / entry["document"]).is_file() + assert all((out / name).is_file() for name in entry["attachments"]) + assert ( + recorder.statuses[result.execution_id][-1]["details"]["customer_case"] + == "acme-webhooks" + ) + lessons = ( + tmp_path + / "lessons" + / "candidates" + / "acme-webhooks" + / f"{result.execution_id}.json" + ) + assert lessons.is_file() + assert recorder.lessons[result.execution_id]["customer_case"] == "acme-webhooks" + + +async def test_two_executions_of_one_customer_case_sit_side_by_side(tmp_path): + first = await make_engine(tmp_path, FakeAgentRuntime(happy_path_turns())).start( + "Ingestion", pre_approved=True, customer_case="acme-webhooks" + ) + second = await make_engine(tmp_path, FakeAgentRuntime(happy_path_turns())).start( + "Ingestion, revised", pre_approved=True, customer_case="acme-webhooks" + ) + + case = tmp_path / "deliverables" / "cases" / "acme-webhooks" + assert {path.name for path in (case / "executions").iterdir()} == { + first.execution_id, + second.execution_id, + } + history = json.loads((case / "intent" / "history.json").read_text(encoding="utf-8")) + assert history["customer_case"] == "acme-webhooks" + assert [ + (i["version"], i["workflow_request"], i["status"], i["execution"]) + for i in history["intents"] + ] == [ + (1, "Ingestion", "completed", f"executions/{first.execution_id}"), + (2, "Ingestion, revised", "completed", f"executions/{second.execution_id}"), + ] + assert "Ingestion, revised" in (case / "intent" / "002.md").read_text() + assert first.state["intent_version"] == 1 and second.state["intent_version"] == 2 + # A Customer case groups Executions; it never feeds one into the next. + assert second.state["conversation"][0]["text"] == "Ingestion, revised" + assert "deliverables" in second.state and first.state != second.state + + +@pytest.mark.parametrize( + "bad", ["../etc", "Acme", "acme/webhooks", "", "-acme", "a" * 65, 7] +) +async def test_a_customer_case_that_is_not_a_safe_slug_is_refused(tmp_path, bad): + engine = make_engine(tmp_path, FakeAgentRuntime(happy_path_turns())) + + with pytest.raises(ValueError, match="customer_case"): + await engine.start("Ingestion", pre_approved=True, customer_case=bad) + + assert not (tmp_path / "deliverables").exists() + + +async def test_an_execution_without_a_customer_case_is_grouped_as_unassigned(tmp_path): + result = await make_engine(tmp_path, FakeAgentRuntime(happy_path_turns())).start( + "Ingestion", pre_approved=True + ) + + assert result.state["customer_case"] == "unassigned" + assert [path.name for path in (tmp_path / "deliverables").iterdir()] == ["cases"] + assert [path.name for path in (tmp_path / "deliverables" / "cases").iterdir()] == [ + "unassigned" + ] + + +async def test_the_intent_is_on_record_as_soon_as_an_execution_starts(tmp_path): + runtime = FakeAgentRuntime( + {"orchestrator": [[ask_user("Which region should this run in?")]]} + ) + engine = make_engine(tmp_path, runtime) + + paused = await engine.start("Ingest signed webhooks", customer_case="acme-webhooks") + + assert paused.status == "awaiting_user" + intent = tmp_path / "deliverables" / "cases" / "acme-webhooks" / "intent" + statement = (intent / "001.md").read_text(encoding="utf-8") + assert "Ingest signed webhooks" in statement + assert paused.execution_id in statement + [entry] = json.loads((intent / "history.json").read_text())["intents"] + assert entry["status"] == "in_progress" + assert entry["statement"] == "intent/001.md" + assert entry["execution_id"] == paused.execution_id diff --git a/tests/execution/test_file_arguments.py b/tests/execution/test_file_arguments.py index b9235ee..33a5878 100644 --- a/tests/execution/test_file_arguments.py +++ b/tests/execution/test_file_arguments.py @@ -36,12 +36,18 @@ async def test_submission_takes_attachments_as_a_list(): content=GUIDANCE, attachments=[ {"path": "terraform/main.tf", "content": "resource {}"}, - {"path": "terraform/variables.tf", "content": ""}, + {"path": "terraform/variables.tf", "content": "variable {}"}, + {"path": "implementation.json", "content": "[]"}, ], ) assert result.outcome == Submitted( - GUIDANCE, {"terraform/main.tf": "resource {}", "terraform/variables.tf": ""} + GUIDANCE, + { + "terraform/main.tf": "resource {}", + "terraform/variables.tf": "variable {}", + "implementation.json": "[]", + }, ) diff --git a/tests/execution/test_ledger.py b/tests/execution/test_ledger.py index d85f251..757c4d7 100644 --- a/tests/execution/test_ledger.py +++ b/tests/execution/test_ledger.py @@ -33,14 +33,11 @@ def through_phase_one(ledger: Ledger) -> None: def through_phase_two(ledger: Ledger) -> None: through_phase_one(ledger) produce( - ledger, - K.PRODUCT_SELECTION, - K.ARCHITECTURE_DIAGRAM, - K.ARCHITECTURE_DESCRIPTION, - K.DESIGN_RECOMMENDATIONS, - K.DEPLOYMENT_GUIDANCE, + ledger, K.PRODUCT_SELECTION, K.DESIGN_RECOMMENDATIONS, K.TARGET_ARCHITECTURE ) approve(ledger, P.SOLUTION_ARCHITECTURE) + produce(ledger, K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE) + approve(ledger, P.SOLUTION_IMPLEMENTATION) def through_phase_three(ledger: Ledger) -> None: @@ -80,18 +77,18 @@ def test_cross_phase_dependency_needs_the_earlier_phase_approved(): def test_independent_work_becomes_ready_together(): ledger = Ledger() through_phase_one(ledger) - produce(ledger, K.PRODUCT_SELECTION) + produce( + ledger, K.PRODUCT_SELECTION, K.DESIGN_RECOMMENDATIONS, K.TARGET_ARCHITECTURE + ) - assert set(ledger.ready_work()) == { - K.ARCHITECTURE_DIAGRAM, - K.DESIGN_RECOMMENDATIONS, - } + # Nothing in implementation is ready until the design is approved. + assert ledger.ready_work() == () - produce(ledger, K.ARCHITECTURE_DIAGRAM) + approve(ledger, P.SOLUTION_ARCHITECTURE) assert set(ledger.ready_work()) == { K.ARCHITECTURE_DESCRIPTION, - K.DESIGN_RECOMMENDATIONS, + K.DEPLOYMENT_GUIDANCE, } @@ -259,10 +256,12 @@ def test_reopen_cascades_to_dependents_and_withdraws_affected_approvals(): assert ledger.status(K.VALIDATION_RESULTS) is DeliverableStatus.PENDING assert ledger.status(K.PRODUCT_SELECTION) is DeliverableStatus.SUBMITTED assert ledger.phase_status(P.REQUIREMENTS_DISCOVERY) is PhaseStatus.APPROVED - assert ledger.phase_status(P.SOLUTION_ARCHITECTURE) is PhaseStatus.OPEN + # Revising the code leaves the approved design standing. + assert ledger.phase_status(P.SOLUTION_ARCHITECTURE) is PhaseStatus.APPROVED + assert ledger.phase_status(P.SOLUTION_IMPLEMENTATION) is PhaseStatus.OPEN assert ledger.phase_status(P.SOLUTION_VALIDATION) is PhaseStatus.OPEN assert set(result.withdrawn_approvals) == { - P.SOLUTION_ARCHITECTURE, + P.SOLUTION_IMPLEMENTATION, P.SOLUTION_VALIDATION, } assert ledger.revisions(K.DEPLOYMENT_GUIDANCE) == 1 @@ -278,15 +277,15 @@ def test_reopen_invalidates_attempts_of_dependents_already_in_progress(): ledger = Ledger() through_phase_one(ledger) produce(ledger, K.PRODUCT_SELECTION) - attempt = ledger.start([K.ARCHITECTURE_DIAGRAM], actor="orchestrator")[ - K.ARCHITECTURE_DIAGRAM + attempt = ledger.start([K.DESIGN_RECOMMENDATIONS], actor="orchestrator")[ + K.DESIGN_RECOMMENDATIONS ] ledger.reopen(K.PRODUCT_SELECTION, "user prefers GKE", actor="orchestrator") - assert ledger.status(K.ARCHITECTURE_DIAGRAM) is DeliverableStatus.PENDING + assert ledger.status(K.DESIGN_RECOMMENDATIONS) is DeliverableStatus.PENDING with pytest.raises(LedgerRefusal, match="attempt"): - ledger.submit(K.ARCHITECTURE_DIAGRAM, attempt, actor="diagrammer") + ledger.submit(K.DESIGN_RECOMMENDATIONS, attempt, actor="design-advisor") def test_reopen_refuses_deliverables_that_were_never_submitted(): @@ -356,3 +355,27 @@ def test_round_trips_through_plain_data(): assert restored.ready_work() == ledger.ready_work() assert restored.max_revisions == 5 assert restored.events == ledger.events + + +def test_revising_the_target_architecture_returns_the_code_to_draft(): + ledger = Ledger() + through_phase_three(ledger) + + result = ledger.reopen( + K.TARGET_ARCHITECTURE, "NFR-1 has no Check on retention", actor="orchestrator" + ) + + assert set(result.reset) == { + K.TARGET_ARCHITECTURE, + K.ARCHITECTURE_DESCRIPTION, + K.DEPLOYMENT_GUIDANCE, + K.VALIDATION_RESULTS, + } + assert set(result.withdrawn_approvals) == { + P.SOLUTION_ARCHITECTURE, + P.SOLUTION_IMPLEMENTATION, + P.SOLUTION_VALIDATION, + } + # The code cannot be rewritten until the revised design is approved again. + produce(ledger, K.TARGET_ARCHITECTURE) + assert ledger.ready_work() == () diff --git a/tests/execution/test_lessons.py b/tests/execution/test_lessons.py new file mode 100644 index 0000000..837a2cc --- /dev/null +++ b/tests/execution/test_lessons.py @@ -0,0 +1,239 @@ +"""Lesson candidates: what an Execution keeps about what went wrong in it.""" + +import json + +from langgraph.checkpoint.memory import InMemorySaver + +from app.adk.fake_runtime import Call, FakeAgentRuntime, sample_submission +from app.adk.runtime import RoleSpec, ToolResult, ToolSpec +from app.agent import ExecutionEngine +from app.recorder import InMemoryRecorder +from app.states.lessons import refusal +from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind, PhaseId + +K = DeliverableKind +P = PhaseId + +ROLES = { + "orchestrator": RoleSpec( + "orchestrator", "Coordinate.", budget=40, skills=("solution-architecture",) + ), + **{ + spec.specialist: RoleSpec(spec.specialist, "Produce.", budget=15) + for spec in DEPENDENCY_GRAPH.values() + }, +} +FAILED = {"check": "K-2", "evidence": "The identity is shared with another service."} +ADDITION = { + "statement": "The service sets a request timeout.", + "applies_to": "E-1", + "reason": "NFR-1 has no Check on timeouts", +} + + +def delegate(*kinds: DeliverableKind) -> Call: + return Call("delegate", {"kinds": [kind.value for kind in kinds]}) + + +def approve(phase: PhaseId) -> Call: + return Call("request_approval", {"phase": phase.value, "summary": "done"}) + + +def specialist(kind: DeliverableKind) -> str: + return DEPENDENCY_GRAPH[kind].specialist + + +def failing_validation() -> Call: + call = sample_submission(K.VALIDATION_RESULTS) + verdicts = json.loads(call.args["attachments"]["verdicts.json"]) + verdicts["checks"][1] = {**FAILED, "verdict": "fail"} + verdicts["proposed_additions"] = [ADDITION] + return Call( + call.tool, + {**call.args, "attachments": {"verdicts.json": json.dumps(verdicts)}}, + ) + + +def turns_with_one_revision() -> dict: + once = { + spec.specialist: [[sample_submission(kind)]] + for kind, spec in DEPENDENCY_GRAPH.items() + } + return { + **once, + "orchestrator": [ + # The first call is refused: requirements are not done yet. + [delegate(K.TECHNICAL_DECOMPOSITION), delegate(K.REQUIREMENTS)], + [delegate(K.TECHNICAL_DECOMPOSITION)], + [approve(P.REQUIREMENTS_DISCOVERY), delegate(K.PRODUCT_SELECTION)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [delegate(K.TARGET_ARCHITECTURE)], + [ + approve(P.SOLUTION_ARCHITECTURE), + delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE), + ], + [approve(P.SOLUTION_IMPLEMENTATION), delegate(K.VALIDATION_RESULTS)], + [ + Call( + "reopen", + {"kind": "deployment_guidance", "reason": "Fix the ingress block."}, + ), + delegate(K.DEPLOYMENT_GUIDANCE), + ], + [approve(P.SOLUTION_IMPLEMENTATION), delegate(K.VALIDATION_RESULTS)], + [approve(P.SOLUTION_VALIDATION), delegate(K.SOLUTION_GUIDE)], + [approve(P.PACKAGING), Call("finish")], + ], + specialist(K.DEPLOYMENT_GUIDANCE): [ + [ + Call("submit_deliverable", {"content": "No headings yet."}), + sample_submission(K.DEPLOYMENT_GUIDANCE), + ], + [sample_submission(K.DEPLOYMENT_GUIDANCE)], + ], + specialist(K.VALIDATION_RESULTS): [ + [failing_validation()], + [sample_submission(K.VALIDATION_RESULTS)], + ], + } + + +async def run(tmp_path, turns, **options): + recorder = InMemoryRecorder() + engine = ExecutionEngine( + runtime=FakeAgentRuntime(turns), + roles=ROLES, + recorder=recorder, + checkpointer=InMemorySaver(), + output_root=tmp_path, + skill_versions={"solution-architecture": "abc123"}, + **options, + ) + result = await engine.start("Ingestion", pre_approved=True) + return result, recorder + + +def of_type(record: dict, kind: str) -> list[dict]: + return [c for c in record["candidates"] if c["type"] == kind] + + +async def test_a_finished_execution_records_what_went_wrong(tmp_path): + result, recorder = await run(tmp_path, turns_with_one_revision()) + + assert result.status == "completed" + record = recorder.lessons[result.execution_id] + + assert of_type(record, "revision") == [ + { + "type": "revision", + "deliverable": "deployment_guidance", + "reason": "Fix the ingress block.", + "requested_by": "orchestrator", + } + ] + assert of_type(record, "failed_check") == [ + {"type": "failed_check", "attempt": 1, **FAILED} + ] + assert of_type(record, "proposed_addition") == [ + {"type": "proposed_addition", "attempt": 1, **ADDITION} + ] + refusals = of_type(record, "refusal") + assert {(r["role"], r["tool"], r["deliverable"]) for r in refusals} == { + ("orchestrator", "delegate", None), + ( + specialist(K.DEPLOYMENT_GUIDANCE), + "submit_deliverable", + "deployment_guidance", + ), + } + assert all(r["message"].startswith(("Refused", "Not submitted")) for r in refusals) + + +async def test_the_record_names_the_execution_and_the_skills_loaded(tmp_path): + result, recorder = await run(tmp_path, turns_with_one_revision()) + + record = recorder.lessons[result.execution_id] + + assert record["execution_id"] == result.execution_id + assert record["status"] == "completed" + assert record["role_skills"]["orchestrator"] == ["solution-architecture"] + assert record["skill_versions"] == {"solution-architecture": "abc123"} + + +async def test_the_record_is_also_written_beside_the_deliverables_tree(tmp_path): + result, recorder = await run(tmp_path, turns_with_one_revision()) + + path = ( + tmp_path + / "lessons" + / "candidates" + / "unassigned" + / f"{result.execution_id}.json" + ) + + assert ( + json.loads(path.read_text(encoding="utf-8")) + == (recorder.lessons[result.execution_id]) + ) + + +async def test_an_execution_that_ends_with_warnings_still_records_lessons(tmp_path): + turns = { + "orchestrator": [[delegate(K.REQUIREMENTS)], []], + specialist(K.REQUIREMENTS): [[]], # stops without submitting + } + + result, recorder = await run(tmp_path, turns) + + assert result.status == "completed_with_warnings" + record = recorder.lessons[result.execution_id] + assert of_type(record, "unfinished") == [ + { + "type": "unfinished", + "deliverable": "requirements", + "role": specialist(K.REQUIREMENTS), + "reason": "stopped", + } + ] + assert not ( + tmp_path / "deliverables" / "cases" / "unassigned" / "executions" + ).exists() + + +async def test_a_cloud_read_refusal_keeps_only_its_leading_words(tmp_path): + async def list_instances() -> ToolResult: + return ToolResult("Discovery gap: project acme-prod-1234 API not enabled.") + + tool = ToolSpec( + "compute__list_instances", + "List instances.", + {"type": "object", "properties": {}}, + list_instances, + tier="cloud_read", + ) + + def factory(role, deliverable, working): + return [tool] if deliverable == "requirements" else [] + + turns = { + "orchestrator": [[delegate(K.REQUIREMENTS)], []], + specialist(K.REQUIREMENTS): [ + [Call("compute__list_instances"), sample_submission(K.REQUIREMENTS)] + ], + } + + result, recorder = await run(tmp_path, turns, tool_factory=factory, max_revisions=3) + await_record = recorder.lessons[result.execution_id] + + # allow_cloud_read is False in a pre-approved Execution, so the gate refuses. + [gap] = of_type(await_record, "refusal") + assert gap["tool"] == "compute__list_instances" + assert "acme-prod-1234" not in gap["message"] + + +def test_refusal_messages_are_bounded(): + item = refusal( + "validator", "validation_results", "terraform_validate", "general", "x" * 900 + ) + + assert len(item["message"]) == 500 diff --git a/tests/execution/test_pillars.py b/tests/execution/test_pillars.py index 18bed8b..d3e3a8e 100644 --- a/tests/execution/test_pillars.py +++ b/tests/execution/test_pillars.py @@ -122,15 +122,15 @@ async def test_tool_factory_assembles_local_mcp_and_consultation_tools(): diagrammer = RoleSpec("diagrammer", "", budget=5, tools=("mermaid_check",)) analyst = RoleSpec("requirements-analyst", "", budget=5, mcp_servers=("compute",)) - assert [t.name for t in factory(diagrammer, "architecture_diagram")] == [ + assert [t.name for t in factory(diagrammer, "architecture_diagram", {})] == [ "mermaid_check" ] - assert [t.name for t in factory(analyst, "requirements")] == [ + assert [t.name for t in factory(analyst, "requirements", {})] == [ "compute__list_instances" ] [consult_tool] = factory( - RoleSpec("design-advisor", "", budget=5), "design_recommendations" + RoleSpec("design-advisor", "", budget=5), "design_recommendations", {} ) await consult_tool.handler(brief="b") assert runtime.runs[0].tools == ("submit_advice", "docs__search") @@ -140,8 +140,171 @@ async def test_tool_factory_gives_the_consultation_only_to_the_design_advisor(): roles = {PILLAR_ADVISOR: ADVISOR} factory = make_tool_factory(FakeAgentRuntime({}), roles, PILLARS) - design = factory(RoleSpec("design-advisor", "", budget=5), "design_recommendations") - other = factory(RoleSpec("decomposer", "", budget=5), "technical_decomposition") + design = factory( + RoleSpec("design-advisor", "", budget=5), "design_recommendations", {} + ) + other = factory(RoleSpec("decomposer", "", budget=5), "technical_decomposition", {}) assert [tool.name for tool in design] == [CONSULT_TOOL] assert list(other) == [] + + +# --- advice remembered across Revisions (iteration 4, step 3) -------------------------- + + +async def test_naming_pillars_reconsults_only_those_and_returns_the_rest_from_memory(): + memory: dict = {} + first = FakeAgentRuntime({PILLAR_ADVISOR: [turn_for_pillar] * 3}) + await consult( + pillar_consultation_tool(first, ADVISOR, PILLARS, memory=memory), brief="v1" + ) + + def revised(task): + pillar = task.context["pillar"] + return [Call("submit_advice", {"content": f"Revised advice for {pillar}."})] + + second = FakeAgentRuntime({PILLAR_ADVISOR: [revised]}) + tool = pillar_consultation_tool(second, ADVISOR, PILLARS, memory=memory) + + result = await consult(tool, brief="v2", pillars=["reliability"]) + + assert [run.task.context["pillar"] for run in second.runs] == ["reliability"] + assert "## reliability\n\nRevised advice for reliability." in result.message + assert ( + "## security (from your earlier consultation)\n\n" + "Use strong defaults for security." in result.message + ) + assert memory["pillar_advice"]["reliability"] == "Revised advice for reliability." + assert set(memory["pillar_advice"]) == set(PILLARS) + + +async def test_omitting_pillars_consults_every_pillar_afresh(): + memory = {"pillar_advice": {pillar: "old" for pillar in PILLARS}} + runtime = FakeAgentRuntime({PILLAR_ADVISOR: [turn_for_pillar] * 3}) + tool = pillar_consultation_tool(runtime, ADVISOR, PILLARS, memory=memory) + + result = await consult(tool, brief="v2") + + assert len(runtime.runs) == 3 + assert "earlier consultation" not in result.message + assert "old" not in memory["pillar_advice"].values() + + +async def test_failed_advice_is_not_remembered(): + memory: dict = {} + runtime = FakeAgentRuntime({PILLAR_ADVISOR: [advice("security"), []]}) + tool = pillar_consultation_tool( + runtime, ADVISOR, {"security": "s", "reliability": "r"}, memory=memory + ) + + result = await consult(tool, brief="b") + + assert "## reliability\n\nNo guidance" in result.message + assert set(memory["pillar_advice"]) == {"security"} + + +async def test_the_fan_out_shares_the_cap_and_a_cap_of_one_does_not_deadlock(): + import asyncio + + from app.adk.runtime import RunLimiter + + limiter = RunLimiter(1) + in_flight = 0 + peak = 0 + + class SlowRuntime(FakeAgentRuntime): + async def run(self, role, task, tools): + nonlocal in_flight, peak + in_flight += 1 + peak = max(peak, in_flight) + await asyncio.sleep(0.01) + try: + return await super().run(role, task, tools) + finally: + in_flight -= 1 + + runtime = SlowRuntime({PILLAR_ADVISOR: [turn_for_pillar] * 3}) + tool = pillar_consultation_tool(runtime, ADVISOR, PILLARS, limiter=limiter) + + async with limiter.slot(): # the design advisor's own run holds the only slot + result = await asyncio.wait_for(consult(tool, brief="b"), timeout=5) + + assert peak == 1 + assert result.message.count("Use strong defaults") == 3 + + +async def test_pillar_advice_survives_a_revision_through_the_engine(tmp_path): + from langgraph.checkpoint.memory import InMemorySaver + + from app.adk.fake_runtime import sample_submission + from app.agent import ExecutionEngine + from app.recorder import InMemoryRecorder + from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind, PhaseId + + K, P = DeliverableKind, PhaseId + design = DEPENDENCY_GRAPH[K.DESIGN_RECOMMENDATIONS].specialist + roles = { + "orchestrator": RoleSpec("orchestrator", "Coordinate.", budget=40), + PILLAR_ADVISOR: ADVISOR, + **{ + spec.specialist: RoleSpec(spec.specialist, "Produce.", budget=15) + for spec in DEPENDENCY_GRAPH.values() + }, + } + + def delegate(*kinds): + return Call("delegate", {"kinds": [kind.value for kind in kinds]}) + + def approve(phase): + return Call("request_approval", {"phase": phase.value, "summary": "done"}) + + submit = sample_submission(K.DESIGN_RECOMMENDATIONS) + runtime = FakeAgentRuntime( + { + "orchestrator": [ + [delegate(K.REQUIREMENTS)], + [delegate(K.TECHNICAL_DECOMPOSITION)], + [approve(P.REQUIREMENTS_DISCOVERY), delegate(K.PRODUCT_SELECTION)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [ + Call( + "reopen", + {"kind": "design_recommendations", "reason": "Tighten IAM."}, + ), + delegate(K.DESIGN_RECOMMENDATIONS), + ], + [], # stops here: a pre-approved Execution ends with warnings + ], + DEPENDENCY_GRAPH[K.REQUIREMENTS].specialist: [ + [sample_submission(K.REQUIREMENTS)] + ], + DEPENDENCY_GRAPH[K.TECHNICAL_DECOMPOSITION].specialist: [ + [sample_submission(K.TECHNICAL_DECOMPOSITION)] + ], + DEPENDENCY_GRAPH[K.PRODUCT_SELECTION].specialist: [ + [sample_submission(K.PRODUCT_SELECTION)] + ], + design: [ + [Call(CONSULT_TOOL, {"brief": "v1"}), submit], + [Call(CONSULT_TOOL, {"brief": "v2", "pillars": ["security"]}), submit], + ], + PILLAR_ADVISOR: [turn_for_pillar] * 4, + } + ) + engine = ExecutionEngine( + runtime=runtime, + roles=roles, + recorder=InMemoryRecorder(), + checkpointer=InMemorySaver(), + output_root=tmp_path, + tool_factory=make_tool_factory(runtime, roles, PILLARS), + ) + + result = await engine.start("Ingestion", pre_approved=True) + + advisor_runs = [r for r in runtime.runs if r.role == PILLAR_ADVISOR] + assert [r.task.context["pillar"] for r in advisor_runs[3:]] == ["security"] + second = [r for r in runtime.runs if r.role == design][1] + assert "## reliability (from your earlier consultation)" in second.results[0][1] + stored = result.state["working"]["design_recommendations"]["pillar_advice"] + assert set(stored) == set(PILLARS) diff --git a/tests/execution/test_presentation.py b/tests/execution/test_presentation.py index b6a2180..484c89c 100644 --- a/tests/execution/test_presentation.py +++ b/tests/execution/test_presentation.py @@ -12,7 +12,7 @@ def test_approval_prompt_explains_the_structured_reply(): "approval": { "phase": "solution_architecture", "summary": "Cloud Run and Pub/Sub", - "deliverables": ["product_selection", "architecture_diagram"], + "deliverables": ["product_selection", "target_architecture"], } } ) @@ -74,3 +74,27 @@ def test_generate_response_maps_deliverables_onto_legacy_artifacts(): assert body["artifacts"]["terraform_code"] == "resource {}" assert body["artifacts"]["solution_guide"] is None assert body["warnings"] == ["revision limit"] + + +def test_the_design_approval_says_what_the_user_is_committing_to(): + text = describe_prompt( + { + "approval": { + "phase": "solution_architecture", + "summary": "Cloud Run and Pub/Sub", + "deliverables": ["target_architecture"], + "target_architecture": { + "elements": 9, + "relationships": 11, + "checks": 23, + "not_applicable": [ + {"recommendation": "DR-9", "reason": "Single region."} + ], + }, + } + } + ) + + assert "9 Elements, 11 Relationships and 23 Checks" in text + assert "No infrastructure code is written until you approve it" in text + assert "Recommendation DR-9 is treated as not applicable: Single region." in text diff --git a/tests/execution/test_requirements_chain.py b/tests/execution/test_requirements_chain.py new file mode 100644 index 0000000..124b4ad --- /dev/null +++ b/tests/execution/test_requirements_chain.py @@ -0,0 +1,616 @@ +"""The Requirements chain: the Target architecture graph and the data files around it. + +ADR-0005: the outcome is understood before code is written, and validation answers +the graph's Checks and nothing else. +""" + +import json + +import pytest +from langgraph.checkpoint.memory import InMemorySaver + +from app.adk.fake_runtime import SAMPLE_DATA, Call, FakeAgentRuntime, sample_submission +from app.adk.runtime import RoleSpec +from app.agent import ExecutionEngine +from app.recorder import InMemoryRecorder +from app.tools.execution import specialist_tools +from app.tools.local import mermaid_check +from app.workflows.chain import validation_outcome +from app.workflows.deliverables import ( + DEPENDENCY_GRAPH, + DeliverableKind, + PhaseId, + check_submission, +) +from app.workflows.target_architecture import ( + GraphError, + chain_gaps, + parse_graph, + render_mermaid, +) + +K = DeliverableKind +P = PhaseId + +REQUIREMENTS = json.loads(SAMPLE_DATA["requirements.json"]) +COMPONENTS = json.loads(SAMPLE_DATA["components.json"]) +PRODUCTS = json.loads(SAMPLE_DATA["products.json"]) +RECOMMENDATIONS = json.loads(SAMPLE_DATA["recommendations.json"]) + + +def graph_data() -> dict: + return json.loads(SAMPLE_DATA["target-architecture.json"]) + + +def problems(data: dict) -> tuple[str, ...]: + with pytest.raises(GraphError) as raised: + parse_graph(json.dumps(data)) + return raised.value.problems + + +def gaps(data: dict, **overrides) -> tuple[str, ...]: + links = { + "requirements": REQUIREMENTS, + "components": COMPONENTS, + "products": PRODUCTS, + "recommendations": RECOMMENDATIONS, + **overrides, + } + return chain_gaps(parse_graph(json.dumps(data)), **links) + + +def upstream(*kinds: DeliverableKind, **replaced: str) -> dict: + """The Deliverables a submission builds on, from the coherent sample.""" + built = {} + for kind in kinds: + args = sample_submission(kind).args + attachments = { + name: replaced.get(name, text) for name, text in args["attachments"].items() + } + built[kind.value] = {"content": args["content"], "attachments": attachments} + return built + + +DESIGN = ( + K.REQUIREMENTS, + K.TECHNICAL_DECOMPOSITION, + K.PRODUCT_SELECTION, + K.DESIGN_RECOMMENDATIONS, +) + + +# --- the graph is well-formed ---------------------------------------------------------- + + +def test_the_sample_graph_parses_into_elements_relationships_and_checks(): + graph = parse_graph(SAMPLE_DATA["target-architecture.json"]) + + assert [element.id for element in graph.elements] == ["E-1", "E-2"] + assert graph.elements[1].component is None # a supporting Element + assert [(r.source, r.target) for r in graph.relationships] == [("E-1", "E-2")] + assert graph.check_ids == ("K-1", "K-2") + assert graph.summary() == { + "elements": 2, + "relationships": 1, + "checks": 2, + "not_applicable": [], + } + + +def test_a_relationship_must_join_two_elements(): + data = graph_data() + data["relationships"][0]["to"] = "E-9" + + assert problems(data) == ( + "target-architecture.json: Relationship R-1 to E-9, which is not an Element", + ) + + +def test_a_check_must_apply_to_something_in_the_graph(): + data = graph_data() + data["checks"][0]["applies_to"] = "E-9" + + assert problems(data) == ( + ( + "target-architecture.json: Check K-1 applies to E-9, " + "which is not an Element or Relationship" + ), + "target-architecture.json: Element E-1 has no Check", + ) + + +def test_every_element_needs_a_check_and_every_id_is_used_once(): + data = graph_data() + data["checks"] = [data["checks"][0]] + data["relationships"][0]["id"] = "E-1" + + assert problems(data) == ( + "target-architecture.json: id E-1 is used more than once", + "target-architecture.json: Element E-2 has no Check", + ) + + +def test_a_check_without_a_statement_is_named(): + data = graph_data() + data["checks"][1]["statement"] = " " + + assert ( + "target-architecture.json.checks[1]: needs a non-empty statement" + in problems(data) + ) + + +@pytest.mark.parametrize("text", ["not json", "[]", '{"elements": "many"}']) +def test_a_graph_that_is_not_the_right_shape_is_refused(text): + with pytest.raises(GraphError): + parse_graph(text) + + +# --- the Requirements chain has no gap ------------------------------------------------- + + +def test_the_sample_chain_is_complete(): + assert gaps(graph_data()) == () + + +def test_a_non_functional_requirement_with_no_check_is_a_gap(): + retention = {"id": "NFR-2", "kind": "non_functional", "text": "Retain 30 days."} + + assert gaps(graph_data(), requirements=[*REQUIREMENTS, retention]) == ( + "Requirement NFR-2 has no Check", + ) + + +def test_a_functional_requirement_is_carried_by_its_components_element(): + # FR-1 is the source of no Check, but C-1 serves it and E-1 realises C-1. + assert not [gap for gap in gaps(graph_data()) if "FR-1" in gap] + + unserved = [{**COMPONENTS[0], "requirements": ["NFR-1"]}] + assert gaps(graph_data(), components=unserved) == ("Requirement FR-1 has no Check",) + + +def test_a_component_with_no_element_is_a_gap(): + replay = {"id": "C-2", "name": "Replay service", "requirements": []} + + assert gaps(graph_data(), components=[*COMPONENTS, replay]) == ( + "Component C-2 has no Element", + ) + + +def test_a_selected_product_that_no_element_uses_is_a_gap(): + armour = [{"component": "C-1", "product": "Example Armor"}] + + assert gaps(graph_data(), products=armour) == ( + "Product Example Armor selected for C-1 appears on no Element", + ) + + +def test_a_recommendation_needs_a_check_or_a_reason_it_does_not_apply(): + cmek = {"id": "DR-2", "pillar": "security", "text": "Use CMEK.", "components": []} + recommendations = [*RECOMMENDATIONS, cmek] + + assert gaps(graph_data(), recommendations=recommendations) == ( + "Recommendation DR-2 has no Check", + ) + + excused = graph_data() + excused["not_applicable"] = [ + {"recommendation": "DR-2", "reason": "No regulated data."} + ] + assert gaps(excused, recommendations=recommendations) == () + assert parse_graph(json.dumps(excused)).summary()["not_applicable"] == [ + {"recommendation": "DR-2", "reason": "No regulated data."} + ] + + +def test_a_check_must_come_from_a_requirement_or_recommendation(): + data = graph_data() + data["checks"][0]["source"] = "my own idea" + + assert gaps(data) == ( + ( + "Check K-1 has source my own idea, which is not a requirement or design " + "recommendation" + ), + "Requirement NFR-1 has no Check", + ) + + +def test_a_target_architecture_with_a_gap_cannot_be_submitted(): + retention = {"id": "NFR-2", "kind": "non_functional", "text": "Retain 30 days."} + built_on = upstream( + *DESIGN, **{"requirements.json": json.dumps([*REQUIREMENTS, retention])} + ) + args = sample_submission(K.TARGET_ARCHITECTURE).args + + assert check_submission( + K.TARGET_ARCHITECTURE, args["content"], args["attachments"], built_on + ) == ("Requirement NFR-2 has no Check",) + assert ( + check_submission( + K.TARGET_ARCHITECTURE, + args["content"], + args["attachments"], + upstream(*DESIGN), + ) + == () + ) + + +# --- the links before the graph -------------------------------------------------------- + + +def test_requirements_need_ids_and_a_kind(): + def missing(items) -> tuple[str, ...]: + args = sample_submission(K.REQUIREMENTS).args + return check_submission( + K.REQUIREMENTS, args["content"], {"requirements.json": json.dumps(items)} + ) + + assert missing(REQUIREMENTS) == () + assert missing([]) == ("requirements.json: lists no requirements",) + assert missing([REQUIREMENTS[0], {**REQUIREMENTS[0], "kind": "must"}]) == ( + "requirements.json: id FR-1 is used more than once", + "requirements.json: FR-1 kind must be one of functional, non_functional", + ) + assert missing([{"id": "FR-1", "kind": "functional"}]) == ( + "requirements.json[0]: needs text", + ) + + +def test_every_functional_requirement_is_served_by_a_component(): + args = sample_submission(K.TECHNICAL_DECOMPOSITION).args + + def missing(components) -> tuple[str, ...]: + return check_submission( + K.TECHNICAL_DECOMPOSITION, + args["content"], + {"components.json": json.dumps(components)}, + upstream(K.REQUIREMENTS), + ) + + assert missing(COMPONENTS) == () + assert missing([{"id": "C-1", "name": "Ingress", "requirements": ["NFR-9"]}]) == ( + "components.json: C-1 serves NFR-9, which is not a requirement", + "components.json: functional requirement FR-1 is served by no component", + ) + + +def test_every_component_gets_a_product_and_recommendations_name_real_components(): + selection = sample_submission(K.PRODUCT_SELECTION).args + advice = sample_submission(K.DESIGN_RECOMMENDATIONS).args + built_on = upstream(K.REQUIREMENTS, K.TECHNICAL_DECOMPOSITION) + + assert check_submission( + K.PRODUCT_SELECTION, + selection["content"], + {"products.json": json.dumps([{"component": "C-7", "product": "X"}])}, + built_on, + ) == ( + "products.json: C-7 is not a component", + "products.json: component C-1 has no product selected", + ) + wandering = [{**RECOMMENDATIONS[0], "components": ["C-7"]}] + assert check_submission( + K.DESIGN_RECOMMENDATIONS, + advice["content"], + {"recommendations.json": json.dumps(wandering)}, + built_on, + ) == ("recommendations.json: DR-1 names C-7, which is not a component",) + + +# --- code and validation answer the graph ---------------------------------------------- + +EVERYTHING_BEFORE_CODE = (*DESIGN, K.TARGET_ARCHITECTURE) + + +def test_deployment_guidance_must_account_for_every_check(): + args = sample_submission(K.DEPLOYMENT_GUIDANCE).args + partial = json.dumps( + [ + {"check": "K-1", "file": "terraform/main.tf", "address": "a"}, + {"check": "K-7", "file": "terraform/elsewhere.tf", "address": "b"}, + ] + ) + + missing = check_submission( + K.DEPLOYMENT_GUIDANCE, + args["content"], + {**args["attachments"], "implementation.json": partial}, + upstream(*EVERYTHING_BEFORE_CODE), + ) + + assert missing == ( + "implementation.json: K-7 is not a Check in the Target architecture", + "implementation.json: Check K-2 is not accounted for", + "implementation.json: K-7 names terraform/elsewhere.tf, which is not attached", + ) + + +def verdicts(**changes) -> str: + data = json.loads(SAMPLE_DATA["verdicts.json"]) + data.update(changes) + return json.dumps(data) + + +def validation_missing(text: str) -> tuple[str, ...]: + args = sample_submission(K.VALIDATION_RESULTS).args + return check_submission( + K.VALIDATION_RESULTS, + args["content"], + {"verdicts.json": text}, + upstream(*EVERYTHING_BEFORE_CODE, K.DEPLOYMENT_GUIDANCE), + ) + + +def test_validation_gives_exactly_one_verdict_per_check(): + one = {"check": "K-1", "verdict": "pass", "evidence": "seen"} + invented = {"check": "K-9", "verdict": "fail", "evidence": "No Cloud Armor rule."} + + assert validation_missing(SAMPLE_DATA["verdicts.json"]) == () + assert validation_missing(verdicts(checks=[one, one, invented])) == ( + "verdicts.json.checks: check K-1 is used more than once", + "verdicts.json.checks: K-9 is not a Check in the Target architecture", + "verdicts.json.checks: Check K-2 is not accounted for", + ) + + +def test_the_validator_cannot_fail_the_code_on_something_the_graph_lacks(): + """What it notices beyond the Checks is a proposed addition, never a failure.""" + addition = { + "statement": "Cloud Armor rate limiting is configured.", + "applies_to": "E-1", + "reason": "NFR-1", + } + text = verdicts(proposed_additions=[addition]) + + assert validation_missing(text) == () + outcome = validation_outcome(text) + assert outcome["failed"] == [] + assert outcome["proposed_additions"] == [addition] + + +def test_a_verdict_needs_evidence_and_a_known_value_and_the_dry_run_a_result(): + vague = [ + {"check": "K-1", "verdict": "probably", "evidence": "x"}, + {"check": "K-2", "verdict": "pass", "evidence": " "}, + ] + + assert validation_missing(verdicts(dry_run={"verdict": "ok"}, checks=vague)) == ( + "verdicts.json.dry_run: needs a verdict (pass, fail, not_run) and evidence", + "verdicts.json.checks[1]: needs evidence", + "verdicts.json.checks: K-1 verdict must be one of pass, fail, not_verifiable", + "verdicts.json.checks: Check K-2 is not accounted for", + ) + + +def test_a_validation_outcome_separates_faults_in_code_from_gaps_in_the_graph(): + checks = [ + {"check": "K-1", "verdict": "fail", "evidence": "min instances is 1"}, + {"check": "K-2", "verdict": "not_verifiable", "evidence": "No such argument."}, + ] + + outcome = validation_outcome(verdicts(checks=checks)) + + assert outcome["failed"] == [{"check": "K-1", "evidence": "min instances is 1"}] + assert outcome["not_verifiable"] == [ + {"check": "K-2", "evidence": "No such argument."} + ] + assert outcome["passed"] == [] + assert outcome["dry_run"]["verdict"] == "pass" + + +# --- the diagram is a view of the graph ------------------------------------------------ + + +async def test_the_diagram_shows_every_element_and_relationship_once(): + graph = parse_graph(SAMPLE_DATA["target-architecture.json"]) + + diagram = render_mermaid(graph) + + assert diagram == render_mermaid(graph) # deterministic + assert diagram.count("Ingress service") == 1 + assert diagram.count("Ingress identity") == 1 + assert diagram.count("-->") == 1 + assert "runs as" in diagram + assert (await mermaid_check(diagram)).message.startswith("Mermaid check passed") + + +async def test_names_with_characters_mermaid_reserves_still_render(): + data = graph_data() + data["elements"][0]["name"] = 'Ingest "edge" [v2] (public) | {x}' + data["elements"][0]["id"] = "svc/ingest.v2" + data["relationships"][0]["from"] = "svc/ingest.v2" + data["checks"][0]["applies_to"] = "svc/ingest.v2" + data["relationships"][0]["kind"] = "calls (HTTPS) | signed" + + diagram = render_mermaid(parse_graph(json.dumps(data))) + + assert (await mermaid_check(diagram)).message.startswith("Mermaid check passed") + assert "svc/ingest.v2" not in diagram + + +async def test_the_engine_draws_the_diagram_when_the_target_architecture_is_submitted(): + submit = specialist_tools( + K.TARGET_ARCHITECTURE, + extra=[], + allow_cloud_read=False, + upstream=upstream(*DESIGN), + )[0] + args = sample_submission(K.TARGET_ARCHITECTURE).args + + result = await submit.handler(**args) + + assert result.outcome.attachments["architecture.mmd"] == render_mermaid( + parse_graph(SAMPLE_DATA["target-architecture.json"]) + ) + + +async def test_a_gap_is_refused_to_the_specialist_with_the_missing_link_named(): + cmek = {"id": "DR-2", "pillar": "security", "text": "Use CMEK.", "components": []} + built_on = upstream( + *DESIGN, **{"recommendations.json": json.dumps([*RECOMMENDATIONS, cmek])} + ) + submit = specialist_tools( + K.TARGET_ARCHITECTURE, extra=[], allow_cloud_read=False, upstream=built_on + )[0] + + result = await submit.handler(**sample_submission(K.TARGET_ARCHITECTURE).args) + + assert result.outcome is None + assert result.message == ( + "Not submitted. The Deliverable is missing: Recommendation DR-2 has no Check" + ) + + +# --- through the engine ---------------------------------------------------------------- + +ROLES = { + "orchestrator": RoleSpec("orchestrator", "Coordinate.", budget=40), + **{ + spec.specialist: RoleSpec(spec.specialist, "Produce.", budget=15) + for spec in DEPENDENCY_GRAPH.values() + }, +} + + +def delegate(*kinds: DeliverableKind) -> Call: + return Call("delegate", {"kinds": [kind.value for kind in kinds]}) + + +def approve(phase: PhaseId) -> Call: + return Call("request_approval", {"phase": phase.value, "summary": "done"}) + + +def specialist(kind: DeliverableKind) -> str: + return DEPENDENCY_GRAPH[kind].specialist + + +def to_design_approval() -> list[list[Call]]: + return [ + [delegate(K.REQUIREMENTS)], + [delegate(K.TECHNICAL_DECOMPOSITION)], + [approve(P.REQUIREMENTS_DISCOVERY), delegate(K.PRODUCT_SELECTION)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [delegate(K.TARGET_ARCHITECTURE)], + ] + + +def engine_for(tmp_path, turns: dict) -> tuple[ExecutionEngine, FakeAgentRuntime]: + runtime = FakeAgentRuntime(turns) + engine = ExecutionEngine( + runtime=runtime, + roles=ROLES, + recorder=InMemoryRecorder(), + checkpointer=InMemorySaver(), + output_root=tmp_path, + ) + return engine, runtime + + +async def test_the_user_approves_the_graph_before_any_code_is_written(tmp_path): + once = { + specialist(kind): [[sample_submission(kind)]] + for kind in (*DESIGN, K.TARGET_ARCHITECTURE) + } + engine, runtime = engine_for( + tmp_path, + { + **once, + "orchestrator": [ + [delegate(K.REQUIREMENTS)], + [delegate(K.TECHNICAL_DECOMPOSITION)], + [approve(P.REQUIREMENTS_DISCOVERY)], + [delegate(K.PRODUCT_SELECTION)], + [delegate(K.DESIGN_RECOMMENDATIONS)], + [delegate(K.TARGET_ARCHITECTURE)], + # Tries to start the code before asking: refused, then asks. + [delegate(K.DEPLOYMENT_GUIDANCE), approve(P.SOLUTION_ARCHITECTURE)], + ], + }, + ) + + first = await engine.start("Ingest webhooks") + paused = await engine.resume( + first.execution_id, + {"approval": {"phase": "requirements_discovery", "decision": "approve"}}, + ) + + assert paused.prompt["approval"]["phase"] == "solution_architecture" + assert paused.prompt["approval"]["target_architecture"] == { + "elements": 2, + "relationships": 1, + "checks": 2, + "not_applicable": [], + } + refused = runtime.runs[-1].results[0] + assert refused[0] == "delegate" and refused[1].startswith("Refused") + assert specialist(K.DEPLOYMENT_GUIDANCE) not in [run.role for run in runtime.runs] + + +async def test_the_orchestrator_is_told_what_validation_decided(tmp_path): + failing = json.loads(SAMPLE_DATA["verdicts.json"]) + failing["checks"][0] = { + "check": "K-1", + "verdict": "fail", + "evidence": "min instances is 1", + } + failed_validation = sample_submission(K.VALIDATION_RESULTS) + failed_validation = Call( + failed_validation.tool, + { + **failed_validation.args, + "attachments": {"verdicts.json": json.dumps(failing)}, + }, + ) + once = { + specialist(kind): [[sample_submission(kind)]] + for kind in (*DESIGN, K.TARGET_ARCHITECTURE, K.ARCHITECTURE_DESCRIPTION) + } + engine, runtime = engine_for( + tmp_path, + { + **once, + "orchestrator": [ + *to_design_approval(), + [ + approve(P.SOLUTION_ARCHITECTURE), + delegate(K.ARCHITECTURE_DESCRIPTION, K.DEPLOYMENT_GUIDANCE), + ], + [approve(P.SOLUTION_IMPLEMENTATION), delegate(K.VALIDATION_RESULTS)], + [ + Call( + "reopen", + { + "kind": "deployment_guidance", + "reason": "K-1 failed: min instances is 1", + }, + ), + delegate(K.DEPLOYMENT_GUIDANCE), + ], + [], + ], + specialist(K.DEPLOYMENT_GUIDANCE): [ + [sample_submission(K.DEPLOYMENT_GUIDANCE)], + [sample_submission(K.DEPLOYMENT_GUIDANCE)], + ], + specialist(K.VALIDATION_RESULTS): [[failed_validation]], + }, + ) + + result = await engine.start("Ingest webhooks", pre_approved=True) + + turns = [run for run in runtime.runs if run.role == "orchestrator"] + before, after = turns[6].task.context, turns[7].task.context + assert before["validation"] is None + assert after["validation"]["failed"] == [ + {"check": "K-1", "evidence": "min instances is 1"} + ] + assert after["validation"]["proposed_additions"] == [] + # Revising the code leaves the approved design standing. + phases = result.state["ledger"]["phases"] + assert phases["solution_architecture"] == "approved" + revised = [ + run for run in runtime.runs if run.role == specialist(K.DEPLOYMENT_GUIDANCE) + ][1] + assert revised.task.context["feedback"] == ["K-1 failed: min instances is 1"] diff --git a/tests/test_artifacts.py b/tests/test_artifacts.py deleted file mode 100644 index dd8de2c..0000000 --- a/tests/test_artifacts.py +++ /dev/null @@ -1,59 +0,0 @@ -import pathlib -import unittest - -ROOT = pathlib.Path(__file__).parents[1] - - -def get_artifact_text(filename): - search_dirs = [ - ROOT / "deliverables" / "as-is", - ROOT / "deliverables" / "target", - ROOT / "deliverables" / "validation", - ROOT / "deliverables" / "guides", - ROOT / "deliverables", - ROOT / "docs", - ROOT, - ] - for d in search_dirs: - candidate = d / filename - if candidate.is_file(): - return candidate.read_text(encoding="utf-8") - raise FileNotFoundError(f"Artifact {filename} not found") - - -class ArtifactTests(unittest.TestCase): - def test_requirements_defer_products(self): - text = get_artifact_text("requirements.md") - self.assertIn("Product selection deferred:", text) - self.assertIn("Open questions", text) - - def test_architecture_has_products_and_flow(self): - text = get_artifact_text("architecture.md") - for product in ("Cloud Run", "Pub/Sub", "Cloud Storage", "Firestore"): - self.assertIn(product, text) - - def test_mermaid_is_flowchart(self): - text = get_artifact_text("architecture.mmd") - self.assertTrue(text.startswith("flowchart")) - self.assertIn("Cloud Run", text) - - def test_terraform_root_is_complete(self): - main = (ROOT / "terraform/main.tf").read_text() - self.assertIn("google_cloud_run_v2_service", main) - self.assertIn("google_pubsub_topic", main) - self.assertNotRegex(main, r"(?i)(password|secret|private_key)\\s*=") - - def test_guide_packages_outputs(self): - guide = get_artifact_text("solution-architecture-guide.md") - for heading in ( - "Requirements", - "Architecture", - "Terraform", - "Validation", - "Verification", - ): - self.assertIn(heading, guide) - - -if __name__ == "__main__": - unittest.main() diff --git a/tests/test_package.py b/tests/test_package.py index a8ce37f..c670fe9 100644 --- a/tests/test_package.py +++ b/tests/test_package.py @@ -1,20 +1,8 @@ -import subprocess from pathlib import Path ROOT = Path(__file__).parents[1] -def test_artifact_validator(): - result = subprocess.run( - ["python3", "scripts/validate_artifacts.py"], - cwd=ROOT, - capture_output=True, - check=False, - text=True, - ) - assert result.returncode == 0, result.stdout + result.stderr - - def test_no_secret_values(): assert ( "replace-with-project-id" diff --git a/tests/tools/test_local.py b/tests/tools/test_local.py index c7fe747..d809a23 100644 --- a/tests/tools/test_local.py +++ b/tests/tools/test_local.py @@ -1,6 +1,7 @@ """Local tools: Mermaid check and Terraform fmt/validate/plan in a scratch directory.""" import shutil +from pathlib import Path import pytest @@ -157,3 +158,88 @@ def test_local_tools_are_built_by_name_with_their_tier(): } with pytest.raises(KeyError, match="terraform_apply"): local_tools(["terraform_apply"], TerraformRunner()) + + +# --- the provider cache ---------------------------------------------------------------- + + +def fake_terraform(tmp_path: Path) -> tuple[Path, Path]: + """A stand-in terraform that records the cache settings it was run with.""" + log = tmp_path / "calls.log" + binary = tmp_path / "terraform" + binary.write_text( + "#!/bin/sh\n" + f'echo "$1 cache=$TF_PLUGIN_CACHE_DIR ' + f'reuse=$TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE" >> {log}\n' + 'echo "Success! The configuration is valid."\n' + ) + binary.chmod(0o755) + return binary, log + + +async def test_providers_are_cached_in_a_directory_the_runner_creates(tmp_path): + binary, log = fake_terraform(tmp_path) + cache = tmp_path / "not" / "yet" / "there" + runner = TerraformRunner(binary=str(binary), plugin_cache_dir=str(cache)) + + result = await runner.validate(VALID_TF) + + assert result.message.startswith("terraform validate passed") + assert cache.is_dir() + # Scratch directories have no lock file, so reuse must be allowed explicitly. + assert log.read_text().splitlines() == [ + f"init cache={cache} reuse=true", + f"validate cache={cache} reuse=true", + ] + + +async def test_without_a_cache_directory_terraform_is_left_to_its_defaults(tmp_path): + binary, log = fake_terraform(tmp_path) + + await TerraformRunner(binary=str(binary)).validate(VALID_TF) + + assert log.read_text().splitlines() == [ + "init cache= reuse=", + "validate cache= reuse=", + ] + + +async def test_concurrent_checks_install_into_the_cache_one_at_a_time(tmp_path): + import asyncio + + marker = tmp_path / "installing" + overlaps = tmp_path / "overlaps" + binary = tmp_path / "terraform" + binary.write_text( + "#!/bin/sh\n" + 'if [ "$1" = init ]; then\n' + f" [ -e {marker} ] && echo overlap >> {overlaps}\n" + f" touch {marker}; sleep 0.2; rm -f {marker}\n" + "fi\n" + "echo ok\n" + ) + binary.chmod(0o755) + runner = TerraformRunner(binary=str(binary), plugin_cache_dir=str(tmp_path / "c")) + + await asyncio.gather(*(runner.validate(VALID_TF) for _ in range(3))) + + assert not overlaps.exists() + + +def test_the_cache_setting_resolves_under_the_repository_and_can_be_disabled(): + from app.config import Settings + + default = Settings(_env_file=None) + assert default.terraform_plugin_cache() == str( + default.BASE_DIR / ".cache" / "terraform-plugins" + ) + assert ( + Settings(_env_file=None, TF_PLUGIN_CACHE_DIR="").terraform_plugin_cache() + is None + ) + assert ( + Settings( + _env_file=None, TF_PLUGIN_CACHE_DIR="/var/cache/tf" + ).terraform_plugin_cache() + == "/var/cache/tf" + ) diff --git a/workflow.yaml b/workflow.yaml index 9786e65..1477168 100644 --- a/workflow.yaml +++ b/workflow.yaml @@ -14,11 +14,16 @@ phases: input: [requirements, technical_decomposition] deliverables: - product_selection - - architecture_diagram - - architecture_description - design_recommendations + - target_architecture + attachments: [target-architecture.json, architecture.mmd] + approval: required # the Target architecture is approved before any code is written + - id: solution_implementation + input: [target_architecture] + deliverables: + - architecture_description - deployment_guidance - attachments: [architecture.mmd, terraform/main.tf, terraform/variables.tf] + attachments: [terraform/main.tf, terraform/variables.tf, implementation.json] approval: required - id: solution_validation input: [deployment_guidance] @@ -34,7 +39,7 @@ verification: - step: 4 check: solution-architecture-guide.md exists and is non-empty - step: 5 - check: workflow.yaml covers the four Phases and required artifacts exist + check: workflow.yaml covers the five Phases and required artifacts exist - step: 6 check: committed revision is published - step: 7