gcp_solution_architecture_agent/app/nodes/package_node.py

"""Phase 3: Solution Guide Packaging Node."""

import logging
from typing import Any, Dict
from app.states.state import GCPArchitectureState
from app.skills.loader import SkillLoader

logger = logging.getLogger(__name__)


def package_node(state: GCPArchitectureState, skill_loader: SkillLoader) -> Dict[str, Any]:
    """Processes Phase 3 Packaging: assemble final solution-architecture-guide.md document."""
    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: 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)
{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()}
```

### 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()}
```

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()}

### 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", [])
    if "packaging_guide" not in active_skills:
        active_skills.append("packaging_guide")

    status_summary = {
        "phases_completed": ["discover", "design", "validate", "package"],
        "validation_passed": state.get("validation_passed", True),
        "total_active_skills": len(active_skills),
    }

    return {
        "solution_guide": solution_guide,
        "current_phase": "package",
        "active_skills": active_skills,
        "status_summary": status_summary,
    }