refactored: to utilise the google adk and production grade agent

app/nodes/__init__.py

@@ -3,6 +3,7 @@
 from .design_node import design_node
 from .discover_node import discover_node
 from .package_node import package_node
+from .source_discover_node import source_discover_node
 from .validate_node import validate_node
 
-__all__ = ["discover_node", "design_node", "validate_node", "package_node"]
+__all__ = ["source_discover_node", "discover_node", "design_node", "validate_node", "package_node"]

app/nodes/design_node.py

@@ -4,6 +4,7 @@ import logging
 from typing import Any, Dict
 from app.states.state import GCPArchitectureState
 from app.skills.loader import SkillLoader
+from app.tools.mcp_developer_knowledge import get_mcp_client
 
 logger = logging.getLogger(__name__)
 
@@ -13,12 +14,18 @@ def design_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[
     logger.info("Executing design_node")
     skill_prompt = skill_loader.format_skills_for_prompt("design")
 
-    architecture_doc = """# Phase 1 — Architecture & Product Selection
+    # Developer Knowledge MCP Grounding Search
+    mcp_client = get_mcp_client()
+    mcp_knowledge = mcp_client.search_documents(query="Cloud Run PubSub event-driven architecture", category="compute")
+    docs = mcp_knowledge.get("documents", [])
+    citations_str = "\n".join([f"- [{doc['title']}]({doc['uri']})" for doc in docs[:3]]) if docs else "- [Google Cloud Architecture Framework](https://cloud.google.com/architecture/framework)"
+
+    architecture_doc = f"""# 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 (Bucket Storage for Durable Audit Event Replay)
+- **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)
 
@@ -31,9 +38,12 @@ def design_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[
 - 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)
+{citations_str}
 """
 
-    mermaid_diagram = """graph TD
+    mermaid_diagram = """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]
@@ -57,6 +67,21 @@ provider "google" {
   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"

app/nodes/package_node.py

@@ -13,46 +13,124 @@ def package_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict
     logger.info("Executing package_node")
     skill_prompt = skill_loader.format_skills_for_prompt("package")
 
+    src_doc = state.get("source_discovery_doc", "")
+    src_mmd = state.get("source_mermaid_diagram", "")
     req_doc = state.get("requirements_doc", "")
     arch_doc = state.get("architecture_doc", "")
     mmd_doc = state.get("mermaid_diagram", "")
     tf_doc = state.get("terraform_code", "")
     val_doc = state.get("validation_results", "")
 
-    solution_guide = f"""# Google Cloud Solution Architecture Guide
+    solution_guide = f"""# Google Cloud solution architecture: Event-Driven Regional Workload
 
-## Executive Overview
-This document serves as the comprehensive reference architecture guide for an event-driven, highly available Google Cloud application.
+## 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.
 
-## Functional requirements
+## 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.
 
-## Selected products
-- **Compute**: Google Cloud Run
-- **Messaging**: Google Cloud Pub/Sub
-- **Storage**: Google Cloud Storage
-- **Identity & Access**: Google Cloud IAM Service Accounts
+### 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.
 
-## Architecture Diagram (Mermaid)
+### 2.3. Current state (As-Is Architecture)
+{src_doc.strip()}
+
+```mermaid
+{(src_mmd or "flowchart TD\n    Client --> LegacyApp").strip()}
+```
+
+### 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 <br> **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 <br> **Cons**: Complex cluster management |
+| **Storage** | **Google Cloud Storage & Firestore** | Durable object retention with lifecycle rules & NoSQL document database | Cloud SQL | **Pros**: Relational ACID support <br> **Cons**: Less flexible scaling for unstructured event logs |
+
+### 4.2. Architecture diagram (Mermaid)
 ```mermaid
 {mmd_doc.strip()}
 ```
 
-## Infrastructure Blueprint (Terraform)
+### 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
 {tf_doc.strip()}
 ```
 
-## Validation results
+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)
 {val_doc.strip()}
 
-## Deployment & Operations Runbook
-1. Initialize Terraform: `terraform init`
-2. Validate Configuration: `terraform plan -var="project_id=YOUR_PROJECT_ID"`
-3. Deploy Blueprint: `terraform apply`
+### 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)
 """
 
     active_skills = state.get("active_skills", [])

app/nodes/source_discover_node.py

@@ -0,0 +1,43 @@
+"""Phase 0a: Existing Source Environment Discovery Node."""
+
+import logging
+import re
+from typing import Any, Dict
+from app.states.state import GCPArchitectureState
+from app.skills.loader import SkillLoader
+from app.tools.gcp_scanner import GCPEnvironmentScanner
+
+logger = logging.getLogger(__name__)
+
+
+def source_discover_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
+    """Processes Phase 0a Source Environment Discovery: documents existing as-is architecture before target migration."""
+    logger.info("Executing source_discover_node")
+    skill_prompt = skill_loader.format_skills_for_prompt("source_discover")
+
+    # Extract target GCP project ID from request if specified
+    request_summary = state.get("workflow_request", "")
+    project_id = state.get("project_id")
+    if not project_id and request_summary:
+        match = re.search(r"project\s+([a-z0-9-]+)", request_summary, re.IGNORECASE)
+        if match:
+            project_id = match.group(1)
+
+    # Run live GCP environment scanner
+    scanner = GCPEnvironmentScanner(project_id=project_id)
+    scan_result = scanner.scan_environment()
+    report = scanner.format_scan_report(scan_result)
+
+    source_discovery_doc = report["doc"]
+    source_mermaid_diagram = report["mermaid"]
+
+    active_skills = state.get("active_skills", [])
+    if "source_discovery" not in active_skills:
+        active_skills.append("source_discovery")
+
+    return {
+        "source_discovery_doc": source_discovery_doc,
+        "source_mermaid_diagram": source_mermaid_diagram,
+        "current_phase": "source_discover",
+        "active_skills": active_skills,
+    }