☁️ Cloud Architecture Agent Specification¶

🎯 Purpose¶

The Cloud Architecture Agent is responsible for designing a region-aware, multi-cloud, high-availability architecture for all ConnectSoft-generated services and environments.

It ensures that:

Services are placed in optimal cloud regions
Latency, data residency, and compliance constraints are respected
Global scalability, DR, and performance zones are enforced
Outputs are multi-cloud ready, portable across Azure, AWS, GCP
Agent-generated services remain resilient and observably located

💡 Why This Agent Matters¶

In a platform supporting thousands of SaaS microservices and multiple tenants, cloud architecture cannot be static or manually defined.

Without this agent:

Services may be deployed to suboptimal or disallowed regions
Redundancy and failover may be missing
Multi-cloud deployments may become inconsistent or vendor-locked
Latency-sensitive workloads (e.g., real-time APIs) may suffer
Compliance (GDPR, HIPAA, FedRAMP) may be violated unintentionally

With this agent:

✅ Services are region-optimized for latency, cost, and user distribution
✅ Environments are automatically scaled across zones and clouds
✅ Multi-region DR/failover strategies are pre-wired into the platform
✅ Compliance guardrails (e.g., EU-only, gov clouds) are enforced via blueprint logic
✅ Platform orchestration agents can reference a canonical region map per service

🧠 Cloud-Aware Planning Use Cases¶

Use Case	Cloud Architecture Agent Role
Global API latency minimization	Places services closest to majority of users
Multi-cloud DR failover	Defines primary/secondary/tertiary cloud regions
Cost-aware cluster placement	Suggests low-cost but high-throughput zone combinations
FedRAMP or regional regulation	Limits service deployment to approved regions only
Capacity overflow	Pushes burstable services to overflow regions/zones

🧭 Factory Pipeline Context¶

flowchart TD
    SolutionArchitect --> CloudArchitect
    InfrastructureArchitect --> CloudArchitect
    ApplicationArchitect --> CloudArchitect
    CloudArchitect --> DevOpsArchitect
    CloudArchitect --> ObservabilityAgent
    CloudArchitect --> MultiCloudProvisioner

Hold "Alt" / "Option" to enable pan & zoom

🔁 Sample Impact Example¶

Input: NotificationService, Staging, user base = EU + East US
Agent Output:
- primary_region: westeurope
- failover_region: eastus2
- replication: GRS
- cloud_targets: Azure + AWS

✅ Deliverables Supported by This Agent¶

Outcome	Enabled By Agent
🌐 Region-based service placement	✅
☁️ Multi-cloud awareness	✅
📉 Latency optimization	✅
⚖️ Cost and quota-aware decisioning	✅
🚨 Compliance and locality enforcement	✅
📡 Regional observability pre-configuration	✅

📡 Scope of Influence¶

The Cloud Architecture Agent defines the macro-level cloud topology for the entire ConnectSoft SaaS platform, influencing where and how infrastructure and services are:

Deployed across cloud regions and zones
Scaled across clusters and clouds
Replicated for resilience and DR
Constrained for compliance, latency, and sovereignty
Optimized for availability, cost, and performance

It does not provision infrastructure directly — that’s the job of the Infrastructure Architect Agent — but it directs where and how services should be provisioned.

🔧 What This Agent Controls¶

Layer	Influence
Region selection	Picks best cloud regions per service/environment
Multi-cloud support	Suggests primary and secondary cloud providers
Availability Zones (AZs)	Assigns services to specific AZs for HA deployments
Failover/Disaster Recovery (DR)	Suggests secondary zones for automatic or manual failover
Replication strategies	Defines GRS, ZRS, LRS for storage; geo-distributed clusters for compute
Data residency policies	Enforces compliance by excluding forbidden regions
Edge locations	Recommends CDN PoPs or ingress locations (Azure Front Door, CloudFront)
Cloud-specific cluster topology	Suggests AKS/EKS/GKE parameters based on service class
Cost zone prioritization	Aligns burstable or dev workloads to lower-cost zones/tiers

🏗️ What It Does Not Control Directly¶

Layer	Owned By
Actual cluster provisioning	Infrastructure Architect Agent
Secrets, identities, RBAC	Security Architect Agent
Pipeline artifacts	DevOps Architect Agent
Observability spans and logs	Observability Agent
Low-level DNS + IP plans	Network & Infra layer (still informed by CloudArch outputs)

🌍 Cloud-Specific Considerations¶

Platform	This Agent Handles
Azure	Region pairing (e.g., East US 2 + Central US), sovereign regions (e.g., Germany, GovCloud)
AWS	AZ awareness, placement groups, regional resilience (us-west-1 + us-east-1)
GCP	Multi-zone clusters, compliance locality hints (e.g., europe-west4 for GDPR)
Hybrid	Assigns regional aliases (e.g., `edge-west`, `onprem-eu1`) for internal zone planning

🌐 Influence on Other Agents¶

Agent	Dependency
Infrastructure Architect Agent	Uses region plan to place AKS/EKS/GKE, storage, vaults
DevOps Architect Agent	Applies cloud-region constraints to deployment stages
Observability Agent	Routes metrics/logs to regional OTEL backends
Security Architect Agent	Validates region-specific RBAC and data protection compliance
Platform Orchestrator	Balances workloads by reading zone-capacity and regional quotas

✅ Summary¶

Scope Area	Controlled by Agent
🌍 Cloud Regions	✅
☁️ Cloud Provider Targets	✅
🔁 Multi-region replication	✅
⚡ Zone-specific latency models	✅
🛡️ Region-based compliance enforcement	✅
🔀 DR/Failover topology	✅
💵 Cost-aware zone selection	✅

📋 Core Responsibilities¶

The Cloud Architecture Agent is responsible for designing a cloud-scalable, compliant, and region-aware deployment blueprint for every ConnectSoft service and environment.

This blueprint defines:

Primary cloud regions and failover locations
Availability zone distribution
Cross-cloud scaling plans
Compliance-enforced constraints
Replication, performance tier, and zone-capacity guidelines

🧭 1. Region & Zone Selection¶

Task	Output
Select primary deployment region per service/environment	`cloud-region-map.yaml`
Define preferred Availability Zones for each region	`zone-allocation.yaml`
Recommend fallback regions with lower latency or cost	`replication-strategy.yaml`
Avoid forbidden regions (e.g., due to compliance)	Enforced in output & metadata
Inject compliance-required region hints (e.g., EU-only)	Included in metadata and validation spans

☁️ 2. Cloud Provider Targeting¶

Task	Output
Determine whether service should run on Azure, AWS, GCP	`cloud-region-map.yaml` (multi-cloud section)
Suggest multi-cloud fallback if primary region fails	Included in `replication-strategy.yaml`
Allow user preferences (e.g., Azure-first) if performance is comparable	Evaluated via `latency_map.json` + `cloud-preference.yaml`

🔁 3. Replication, Redundancy & Failover Strategy¶

Task	Output
Define GRS/ZRS/LRS or cross-zone replicas	`replication-strategy.yaml`
Recommend active-active or active-passive model	Based on service classification (critical, burstable, etc.)
Assign failover priorities	Included in regional metadata
Estimate blast radius per zone/region	Included in optional `zone-risk-map.yaml`

🛡️ 4. Compliance-Aware Region Filtering¶

Task	Output
Enforce residency (e.g., EU-only, US Gov)	Included in `region-constraints.yaml`
Avoid sanctioned or high-risk zones	Maintained via `prohibited-regions.yaml`
Map data protection categories to region classes	Inferred from `data-sensitivity-level.yaml`
Validate service isn’t deployed in non-compliant region	Emit `CloudComplianceViolation` if invalid

📊 5. Cost & Capacity Optimization¶

Task	Output
Suggest burstable regions for dev/test workloads	`zone-capacity-map.yaml`
Map high-cost zones to critical workloads only	Flag in output metadata
Recommend spot/preemptible support	For staging & ephemeral environments
Align services to tiered resource classes	e.g., `standard`, `high-throughput`, `memory-optimized`

📈 6. Observability Hints¶

Task	Output
Define OTEL exporter endpoints by region	Injected into `otel-agent-config.yaml`
Suggest span propagation zones	Used by Observability Agent
Route log/metric pipelines to low-latency endpoints	Used by DevOps + OTEL collectors

📢 7. Lifecycle Emission & Metadata¶

Task	Output
Emit `CloudArchitecturePlanPublished` event with trace info	JSON lifecycle event
Include cloud strategy metadata in `infra-metadata.json`	Consumed by DevOps/Infra/Observability agents
Log multi-region topology in Mermaid (`cloud-strategy.mmd`)	Diagram of regions, failovers, cloud providers
Support trace-based region diffing	Enables change impact detection and rollback

✅ Summary Table¶

Responsibility	Artifact
Region/zone map	`cloud-region-map.yaml`
Cloud preferences & failovers	`replication-strategy.yaml`
Compliance and constraints	`region-constraints.yaml`
Cost/capacity modeling	`zone-capacity-map.yaml`
OTEL + span routing	`otel-agent-config.yaml`
Events	`CloudArchitecturePlanPublished`

📥 Core Inputs¶

The Cloud Architecture Agent consumes infrastructure topology, service metadata, latency maps, and compliance policies from upstream agents and platform-level definitions.
It uses this input to produce cloud-optimized deployment blueprints with regional, failover, and provider-aware decisions.

📂 Required Input Artifacts¶

Artifact	Source Agent	Purpose
`solution-architecture.md`	Solution Architect Agent	Overall cloud and service structure
`application-architecture.md`	Application Architect Agent	Service zones, grouping, access paths
`resource-configuration.yaml`	Cloud Architect or Infra Agent	Preferred regions, zone requirements, compute classes
`identity-policy.yaml`	Security Architect Agent	Defines data protection class and region-level RBAC constraints
`field-retention-map.yaml`	Data Architect Agent	Infers data residency or replication needs
`observability-policy.yaml`	Observability Agent	Defines OTEL span zones and metric collection points
`latency-map.json`	Platform Service	Region-to-region network latency and round-trip metrics
`cloud-preference.yaml` (optional)	Tenant/Service Config	Preferred cloud provider or region
`prohibited-regions.yaml` (optional)	Compliance Policy	Banned or restricted zones for this customer/org

📘 Sample: `resource-configuration.yaml`¶

service_class: critical
regions:
  preferred: [eastus2, westeurope]
  avoid: [southcentralus, brazilsouth]
replication: GRS
zones_required: true
burstable: false
cloud_targets: [azure, aws]

📘 Sample: `field-retention-map.yaml`¶

fields:
  - name: customer_ssn
    sensitivity: high
    retention_policy: PERSIST_7_YEARS
    residency_required: EU
  - name: user_id
    sensitivity: medium
    residency_required: Global

📘 Sample: `latency-map.json`¶

{
  "us-east-1": {
    "eu-west-1": 91,
    "us-west-2": 47
  },
  "westeurope": {
    "northeurope": 23,
    "eastus": 87
  }
}

📘 Sample: `cloud-preference.yaml`¶

cloud: azure
region: eastus2
reason: billing integration + proximity to HQ
fallback:
  - aws: us-east-1
  - azure: westeurope

📘 Sample: `prohibited-regions.yaml`¶

regions:
  - chinaeast2
  - usgovvirginia
  - brazilsouth
reasons:
  - Data localization law conflict
  - Not authorized for export

✅ Input Validation Rules¶

Rule	Description
Service class must be defined (`critical`, `batch`, `dev`)	✅
At least one region or provider must be declared or inferred	✅
If `residency_required`, region set must intersect allowed zones	✅
Latency map must cover all preferred and fallback regions	✅
Prohibited regions must be excluded from all suggestions	✅
If `cloud_targets` not specified, Azure is assumed by default	✅

🧩 Semantic Prompt Mapping¶

All input artifacts are resolved into a structured object that the agent transforms into:

cloud-region-map.yaml
replication-strategy.yaml
region-constraints.yaml
CloudArchitecturePlanPublished lifecycle event

📤 Core Outputs¶

The Cloud Architecture Agent produces a structured, validated, and traceable cloud deployment blueprint for each service/environment pair.
These outputs guide infrastructure provisioning, DevOps pipelines, failover planning, observability configuration, and compliance enforcement.

📦 Artifact Summary¶

Artifact	Format	Purpose
`cloud-region-map.yaml`	YAML	Primary, secondary, and tertiary region assignments
`replication-strategy.yaml`	YAML	Defines redundancy model: active-active/passive, GRS/ZRS/LRS
`zone-capacity-map.yaml`	YAML	Maps services to available capacity tiers (cost/performance)
`region-constraints.yaml`	YAML	Banned, required, or restricted regions
`cloud-strategy.mmd`	Mermaid	Visual diagram of regional topology and cloud provider layout
`otel-agent-config.yaml` (enriched)	YAML	Adds region-specific OTEL exporter hints
`cloud-metadata.json`	JSON	Traceable summary of region/cloud decisions per service
`CloudArchitecturePlanPublished`	JSON Event	Notifies downstream agents of new plan availability

🧾 Example: `cloud-region-map.yaml`¶

service: NotificationService
environment: Production
cloud_targets:
  - provider: azure
    primary_region: eastus2
    failover_region: centralus
    zones: [1, 2, 3]
  - provider: aws
    fallback_region: us-west-2
    active: false

🧾 Example: `replication-strategy.yaml`¶

replication:
  type: active-passive
  storage_mode: GRS
  compute_mode: zonal-redundant
  data_retention: 7 years
  failover:
    trigger: region-outage
    ttl: 15m

🧾 Example: `region-constraints.yaml`¶

allowed_regions:
  - eastus2
  - centralus
  - westeurope
forbidden_regions:
  - brazilsouth
  - chinaeast2
compliance_scope: EU-only

🧾 Example: `zone-capacity-map.yaml`¶

zone_classes:
  - region: eastus2
    type: standard
    cost_tier: medium
    latency_score: 9
  - region: westeurope
    type: high-performance
    cost_tier: high
    latency_score: 5
  - region: us-west-2
    type: burstable
    cost_tier: low
    latency_score: 7

📈 Example: `cloud-metadata.json`¶

{
  "trace_id": "trace-cloud-98711",
  "service": "NotificationService",
  "environment": "Production",
  "agent_version": "1.1.0",
  "primary_region": "eastus2",
  "failover_region": "centralus",
  "cloud": "Azure",
  "replication": "GRS",
  "compliance": "EU-only",
  "generated_at": "2025-05-02T02:30:00Z"
}

📢 Example: `CloudArchitecturePlanPublished` (Event)¶

{
  "event": "CloudArchitecturePlanPublished",
  "trace_id": "trace-cloud-98711",
  "service": "NotificationService",
  "environment": "Production",
  "outputs": {
    "region_map": "cloud-region-map.yaml",
    "replication": "replication-strategy.yaml",
    "metadata": "cloud-metadata.json"
  },
  "timestamp": "2025-05-02T02:30:00Z"
}

✅ Output Validations (Auto-Enforced)¶

Requirement	Status
All outputs include trace_id, agent_version, environment	✅
Region selections must match compliance and residency policy	✅
At least one cloud region per provider must be assigned	✅
OTEL configuration must include exporter endpoints per region	✅
Mermaid diagram must reflect actual region/provider mapping	✅

🧠 Agent Knowledge Base Overview¶

The Cloud Architecture Agent relies on a curated and evolving knowledge base to make intelligent, policy-aligned decisions about cloud region placement, provider targeting, and failover design.

This includes:

Latency and proximity maps
Compliance constraints
Cost and quota metrics per region
Service classification heuristics
Multi-cloud viability rules
Region pairing and DR reliability scores

📊 1. Latency & Network Proximity¶

Source	Use
`latency-map.json`	Real-time RTT (round-trip time) metrics between cloud regions
`region-latency-matrix`	Used to avoid high-latency failover pairs
`region-affinity-groups.yaml`	Maps nearby zones for multi-region clusters

Sample Logic:¶

If service has critical class and users in both East US and EU → deploy to both eastus2 and westeurope with active-active strategy.

🛡️ 2. Compliance & Residency Knowledge¶

Source	Purpose
`prohibited-regions.yaml`	Blocklisted due to regulatory or operational constraints
`compliance-matrix.yaml`	Maps region capabilities to laws: GDPR, HIPAA, FedRAMP
`sovereign-cloud-zones.yaml`	Lists AWS GovCloud, Azure Germany, etc., and their roles
`data-sensitivity-levels.yaml`	Helps classify services needing region locking or encryption scopes

☁️ 3. Cloud-Specific Capabilities¶

Cloud	Capability Matrix
Azure	GRS/ZRS/LRS options, paired regions, sovereign zones
AWS	AZ redundancy, spot burst availability, DirectConnect
GCP	Multi-zone cluster patterns, regional scopes
Hybrid	Regional aliases for edge + private deployments (`edge-eu1`, `onprem-east`)

Each provider’s current quota availability (optional via APIs) can also guide selection in tight-capacity scenarios.

💰 4. Cost Tiers & Resource Classes¶

Resource Tier	Usage
`low-cost`	Dev, test, CI environments
`standard`	Production for batch, latency-tolerant
`high-performance`	Latency-sensitive, user-facing APIs
`compliant-tier`	For services with regulatory residency (EU-only, GovCloud)

Maps to:

VM SKUs (e.g., D-series vs E-series)
Storage class (e.g., S3 Standard vs IA)
Network egress pricing thresholds

📍 5. Regional Behavior Heuristics¶

Pattern	Action
Too many services in one region → spread via `affinity spillover`
Dev workload in `critical region` → recommend relocation
Same service in multiple clouds → ensure `namespace collision prevention`
Edge-limited environment → suggest private link or CDN fronting

📦 6. Deployment Strategy Hints¶

Strategy	Based On
Active-active	Service class: `real-time`, latency-critical
Active-passive	Service class: `batch`, background worker
Multi-cloud	`redundant: true`, with region-class balance
Hybrid	`cloud_target: hybrid` or `region: onprem-*` in config

🧩 Semantic Memory Mapping¶

All knowledge base components are preloaded into Semantic Kernel memory and indexed by:

Service class (critical, batch, dev)
Target cloud/provider preference
Compliance tags (EU-only, SOC2, HIPAA)
Network proximity and latency groups
Cost optimization level

These are matched automatically when the agent is triggered by the orchestrator.

✅ Knowledge Base Benefits¶

Value	Outcome
🌍 Intelligent placement	Lower latency, optimized cloud targeting
🛡️ Built-in compliance enforcement	No region selected outside policy constraints
💸 Cost-aware guidance	Dev and burst services placed in cheaper zones
📈 Self-correcting drift	Remembers past region plans and avoids unintentional changes
📡 Resilient by default	Region pairing ensures DR and service continuity

🔄 Agent Process Flow¶

The Cloud Architecture Agent executes a well-defined pipeline to transform service and environment metadata into a region-aware, multi-cloud deployment plan, ready to guide infrastructure, DevOps, and compliance enforcement.

Its flow includes input parsing, decision resolution, conflict handling, and artifact generation, all observed via OpenTelemetry spans.

📋 Step-by-Step Flow¶

Step	Description
1️⃣ Input Parsing & Validation	Load the necessary input files such as `resource-configuration.yaml`, `field-retention-map.yaml`, `identity-policy.yaml`, `latency-map.json`, `solution-architecture.md`, `cloud-preference.yaml`, and `prohibited-regions.yaml`. Validate that key parameters like `trace_id`, `environment`, and `service_name` are present, ensure there is at least one preferred region or cloud provider, check compliance rules against selected regions, and verify the required latency and failover logic are covered.
2️⃣ Cloud + Region Resolution	Match the service class (e.g., `critical`) with the primary cloud provider and optimal region based on lowest latency and highest availability. Define the failover region considering proximity, cost, and redundancy, and identify the required availability zones (AZs) for each cloud. Filter out forbidden regions, and those with historical instability or policy violations.
3️⃣ Failover & Replication Planning	Select the replication mode (e.g., GRS, ZRS, LRS). Determine whether the architecture will follow an active-active or active-passive topology, and define the cross-region DNS/failover strategy. Set metric thresholds and TTL (Time-to-Live) for failover switching, and determine the required OTEL exporters for each zone.
4️⃣ Compliance & Residency Enforcement	Match service sensitivity levels (e.g., `high`, `medium`, `low`) against sovereign cloud support, region tagging policies, and the residency required flag (e.g., EU-only, US-only). Emit a violation event (`CloudComplianceViolation`) if any of the compliance requirements are violated.
5️⃣ Zone & Cost Optimization	Suggest zones based on CPU, memory, and storage class requirements, as well as spot/preemptible suitability. Consider region quota availability (if enabled) and historical memory to avoid overloading specific regions.
6️⃣ Artifact Generation	Generate output artifacts such as `cloud-region-map.yaml`, `replication-strategy.yaml`, `zone-capacity-map.yaml`, `region-constraints.yaml`, `cloud-metadata.json`, and `cloud-strategy.mmd`. Inject relevant configurations into `otel-agent-config.yaml` with region-aware exporters for monitoring.
7️⃣ Lifecycle Events + Spans	Emit lifecycle events such as `CloudArchitecturePlanPublished` and `CloudComplianceViolation` (if needed). Create spans for various lifecycle stages: `region_resolved`, `failover_strategy_planned`, `compliance_passed` / `compliance_failed`, and `cloud_strategy_published` for tracking and observability.

1️⃣ Input Parsing & Validation¶

Load inputs:
- resource-configuration.yaml
- field-retention-map.yaml
- identity-policy.yaml
- latency-map.json
- solution-architecture.md
- cloud-preference.yaml
- prohibited-regions.yaml
Validate:
- trace_id, environment, service_name
- At least one preferred region or cloud
- Compliance rules vs selected regions
- Required latency and failover logic coverage

2️⃣ Cloud + Region Resolution¶

Match service class (e.g., critical) with:
- Primary cloud provider
- Optimal region (lowest latency + highest availability)
- Failover region (proximity + cost + redundancy)
- Availability zones (AZs 1–3 per cloud)
Filter out:
- Forbidden regions
- Regions with historical instability or policy violations

3️⃣ Failover & Replication Planning¶

Select replication mode: GRS, ZRS, LRS
Determine:
- Active-active or active-passive topology
- Cross-region DNS/failover strategy
- Metric thresholds and TTLs for switching
- Required OTEL exporters per zone

4️⃣ Compliance & Residency Enforcement¶

Match service sensitivity (high, medium, low) against:
- Sovereign cloud support
- Region tagging policies
- Residency required flag (EU-only, US-only)
Emit violation event (CloudComplianceViolation) if invalid

5️⃣ Zone & Cost Optimization¶

Suggest zones by:
- CPU, memory, storage class requirements
- Spot/preemptible suitability
- Region quota availability (if enabled)
Use historical memory to avoid region overload

6️⃣ Artifact Generation¶

Output:
- cloud-region-map.yaml
- replication-strategy.yaml
- zone-capacity-map.yaml
- region-constraints.yaml
- cloud-metadata.json
- cloud-strategy.mmd
Inject into:
- otel-agent-config.yaml with region-aware exporters

7️⃣ Lifecycle Events + Spans¶

Emit:
- CloudArchitecturePlanPublished
- CloudComplianceViolation (if needed)
Spans:
- region_resolved
- failover_strategy_planned
- compliance_passed / compliance_failed
- cloud_strategy_published

🧠 Diagram: Cloud Agent Flow¶

flowchart TD
    A[Parse Inputs] --> B[Resolve Regions and Clouds]
    B --> C[Apply Compliance + Residency Policies]
    C --> D[Compute Failover and Replication]
    D --> E[Optimize Zones and Capacity]
    E --> F[Emit Outputs + Metadata]
    F --> G[Publish Events + Telemetry Spans]

Hold "Alt" / "Option" to enable pan & zoom

🔁 Auto-Correction & Recovery Behaviors¶

Condition	Correction
No preferred region found	Use lowest latency region from `latency-map.json`
Forbidden region selected	Replace with closest allowed neighbor
Residency violated	Downgrade plan to staging-only, emit violation
Latency too high (>150ms RTT)	Recommend active-active or regional mesh strategy
Cost tier mismatch	Adjust zone to nearest tier with capacity

🛠️ Semantic Kernel Skills Overview¶

The Cloud Architecture Agent is composed of modular Semantic Kernel (.NET) skills, each handling a discrete part of the cloud region resolution and compliance-enforced deployment strategy.
Skills are observable, idempotent, and reuse memory-backed data from previous decisions.

🔧 1. Input Interpretation & Validation Skills¶

Skill	Purpose
`RegionInputParserSkill`	Parses `resource-configuration.yaml`, `latency-map.json`, `prohibited-regions.yaml`
`ResidencyValidatorSkill`	Matches service sensitivity to region constraints
`CloudPreferenceResolverSkill`	Interprets `cloud-preference.yaml` and fallback logic
`LatencyModelValidatorSkill`	Checks latency limits for region pairings

🌍 2. Region and Cloud Selector Skills¶

Skill	Purpose
`PrimaryRegionSelectorSkill`	Chooses best region per cloud based on latency, compliance, cost
`FailoverPlannerSkill`	Selects secondary/tertiary regions with pairing rules
`AvailabilityZoneMapperSkill`	Determines zonal distribution (e.g., AZs 1–3 for high availability)
`MultiCloudOptimizerSkill`	Suggests fallback provider (e.g., AWS if Azure unavailable)

🔁 3. Replication and Topology Planning¶

Skill	Purpose
`ReplicationStrategySkill`	Chooses GRS/ZRS/LRS model + active-active/passive
`ZoneCapacityEvaluatorSkill`	Matches zones to service class and resource tier
`RegionSpilloverPlannerSkill`	Handles regional failover under quota or saturation
`BurstZoneAllocatorSkill`	Assigns dev/test workloads to low-cost regions dynamically

🛡️ 4. Compliance Enforcement & Risk Assessment¶

Skill	Purpose
`ComplianceCheckerSkill`	Validates region against GDPR, HIPAA, FedRAMP
`ForbiddenRegionFilterSkill`	Removes disallowed regions before resolution
`ResidencyViolationNotifierSkill`	Emits `CloudComplianceViolation` event
`SovereignCloudRouterSkill`	Handles Germany/GovCloud/Azure China fallback

🗺️ 5. Artifact Writers & Topology Generators¶

Skill	Output
`CloudRegionMapWriterSkill`	Emits `cloud-region-map.yaml`
`ReplicationStrategyWriterSkill`	Emits `replication-strategy.yaml`
`ZoneCapacityMapWriterSkill`	Emits `zone-capacity-map.yaml`
`RegionConstraintsWriterSkill`	Emits `region-constraints.yaml`
`MermaidStrategyDiagramWriterSkill`	Emits `cloud-strategy.mmd` with region + provider layout
`CloudMetadataManifestWriterSkill`	Emits `cloud-metadata.json` with trace_id and agent_version

📈 6. Lifecycle Events and Span Emitters¶

Skill	Purpose
`CloudPlanPublisherSkill`	Emits `CloudArchitecturePlanPublished` JSON event
`TelemetrySpanEmitterSkill`	Writes spans: `region_resolved`, `compliance_passed`, `replication_mapped`
`OTELConfigInjectorSkill`	Appends exporter config into `otel-agent-config.yaml` by region

🧠 Semantic Match Example¶

query: "Deploy staging analytics service, prefer Azure, latency-sensitive"
resolved:
  primary_region: westeurope
  failover_region: northeurope
  cloud_provider: azure
  replication_type: active-active
  otel_exporter: http://otel-west:4317

🔁 Retry / Fallback Rules (per Skill)¶

Skill	Fallback Trigger	Recovery
`PrimaryRegionSelectorSkill`	No valid region found	Use lowest-latency non-forbidden region
`ReplicationStrategySkill`	Compliance blocks ZRS	Downgrade to GRS, emit warning
`CloudPreferenceResolverSkill`	Cloud preference not available	Use platform default (Azure)
`BurstZoneAllocatorSkill`	No burstable zones	Route to dev-hardened fallback region

📊 Metrics Emitted per Skill¶

Metric	Description
`region_selection_latency_ms`	Time to compute best region
`compliance_violation_total`	Count of residency violations triggered
`zones_recommended_total`	Number of AZs included in region map
`multi_cloud_usage_ratio`	% of plans involving multiple cloud providers
`otel_targets_per_region`	Number of OTEL exporters emitted into config

🧰 Core Technologies and Platforms¶

The Cloud Architecture Agent leverages a blend of cloud telemetry, geo-awareness, semantic orchestration, and compliance data sources to generate accurate, performant, and policy-compliant region assignments across all services.

🧠 Semantic Kernel (.NET)¶

Purpose	Use
Skill orchestration	Modular and traceable functions (region selection, compliance check)
Input prompt parsing	Structured YAML → region/zone strategy maps
Trace injection	Every output includes `trace_id`, `agent_version`, `environment`
Memory injection	Learns from prior region plans and zone decisions

☁️ Cloud Platforms Supported¶

Provider	Details
Azure	Region pairs, sovereign zones (Germany, Gov), GRS/ZRS, cost tiers
AWS	AZ awareness, failover regions, edge PoPs, latency mesh
GCP	Regional clusters, Cloud DNS, network tiers
Hybrid/On-prem	Region aliasing: `onprem-eu1`, `edge-west`, used for latency models and naming

🗺️ Region & Latency Sources¶

Source	Use
ConnectSoft Latency Maps (`latency-map.json`)	RTT-based region selection
Public Cloud APIs	Fallback latency + capacity inputs
GeoDNS / RUM data (planned)	Real-time optimization using traffic patterns
Quota APIs (Azure, AWS) (optional)	Region-level capacity detection for high-scale plans

📜 Compliance & Residency Rules¶

Source	Use
`prohibited-regions.yaml`	Blocklist enforcement
`compliance-matrix.yaml`	Region → regulatory mapping (GDPR, HIPAA, FedRAMP)
`sovereign-cloud-regions.yaml`	Resolves to secure providers (Azure Germany, AWS GovCloud)
`field-retention-map.yaml`	Drives required replication models + data locking

📊 Observability and Span Routing¶

Tool	Role
OpenTelemetry	Emits `region_resolved`, `replication_mapped`, `cloud_strategy_published` spans
otel-agent-config.yaml	Enriched with regional OTLP exporter URLs
Azure Monitor / CloudWatch	Region-aware log/metrics forwarding targets
Prometheus/Grafana (optional)	Used if self-hosted OTEL targets are defined

📁 Output Generation Stack¶

Artifact	Tech
`cloud-region-map.yaml`	YAML, backed by Semantic Kernel + policy model
`cloud-strategy.mmd`	Mermaid syntax rendered using agent zone memory
`cloud-metadata.json`	JSON artifact with traceable keys
`CloudArchitecturePlanPublished`	Event emitted to Event Grid or internal orchestrator
`otel-agent-config.yaml`	Merged with input `observability-policy.yaml`, extended by agent output

🧩 GitOps & CI/CD Integration¶

Integration	Purpose
DevOps Architect Agent	Uses `cloud-region-map.yaml` for pipeline targeting
Infrastructure Architect Agent	Places clusters and DNS zones based on selected region/failover map
ArgoCD / FluxCD (optional)	Receives region-split manifests for multi-region GitOps deployments
Drift Detection Hooks	Uses `cloud-metadata.json` to compare current vs. previous state

📐 Naming Conventions and Resource Mappings¶

Convention	Example
`service-region-env`	`notification-eastus2-prod`
Region tags	`geo:us`, `latency:low`, `class:standard`
OTEL exporter URLs	`http://otel-eastus2:4317`, `https://otel-eu.connectsoft.dev`
Event trace payloads	Contain `trace_id`, `environment`, `agent_version`, and `region_map` refs

✅ Summary of Tools Used¶

Layer	Tools/Technologies
Semantic orchestration	Semantic Kernel (.NET), YAML prompts
Cloud awareness	Latency maps, public cloud APIs
Compliance mapping	Policy YAMLs, field-to-region matrices
Observability	OpenTelemetry, otel-agent-config.yaml
Output formats	YAML, JSON, Mermaid, Events

📜 System Prompt (Bootstrapping Instruction)¶

The system prompt initializes the Cloud Architecture Agent and defines its core mission: generate a region-aware, compliance-safe, multi-cloud deployment strategy for any ConnectSoft service and environment.

This prompt ensures consistent behavior, predictable outputs, and enforced alignment with ConnectSoft principles (latency, redundancy, compliance, modularity).

✅ Full System Prompt (Plain Text)¶

You are the **Cloud Architecture Agent** in the ConnectSoft AI Software Factory.

Your purpose is to evaluate service/environment metadata and produce a complete, traceable, region-aware cloud deployment strategy — including region and zone assignment, failover planning, cloud provider selection, and compliance filtering.

---

## Responsibilities:

1. Parse the following inputs:
   - resource-configuration.yaml
   - solution-architecture.md
   - latency-map.json
   - prohibited-regions.yaml
   - field-retention-map.yaml
   - observability-policy.yaml
   - cloud-preference.yaml (optional)

2. Resolve the following:
   - Primary cloud provider (Azure, AWS, GCP, hybrid)
   - Primary and fallback regions for the current environment
   - Availability zones to be used for compute and storage
   - Replication model (GRS, ZRS, LRS)
   - OTEL exporter endpoints by region
   - Compliance constraints and restricted regions

3. Generate the following artifacts:
   - cloud-region-map.yaml
   - replication-strategy.yaml
   - zone-capacity-map.yaml
   - region-constraints.yaml
   - cloud-metadata.json
   - cloud-strategy.mmd (Mermaid diagram)

4. Publish:
   - CloudArchitecturePlanPublished (JSON event with trace_id and artifact links)

5. Enforce:
   - Data residency and compliance (GDPR, HIPAA, FedRAMP)
   - Avoidance of prohibited regions
   - Injection of traceability metadata (trace_id, agent_version, environment)

---

## Validations:

- All region decisions must respect compliance rules and forbidden zones
- Replication strategy must match the service’s classification (e.g., active-active for real-time APIs)
- Must produce at least one primary region and failover region per environment
- All outputs must include: `trace_id`, `agent_version`, `service_name`, and `environment`
- Any violation must emit a CloudComplianceViolation event with explanation

---

## Observability:

- Emit OpenTelemetry spans for:
   - region_resolved
   - replication_mapped
   - compliance_passed or compliance_failed
   - strategy_published

- Extend `otel-agent-config.yaml` with region-scoped OTLP exporters

---

## Fallback Behavior:

- If no cloud is specified, default to Azure
- If preferred region is forbidden, fallback to nearest low-latency allowed region
- If no region can be found, emit failure and block plan publication

🔐 Policy Alignment¶

The prompt enforces alignment with:

ConnectSoft’s multi-cloud and multi-tenant scalability
Regulatory region requirements
Disaster recovery and HA readiness
Observability-first principles
Clean traceability and automation workflows

📥 Input Prompt Template¶

The Cloud Architecture Agent is activated using a structured YAML-based input prompt that provides contextual data about the service, environment, and preferences for region placement, compliance, and multi-cloud deployment.

This prompt is typically generated by the Platform Orchestrator or the Solution Architect Agent.

✅ Full Input Prompt (YAML)¶

assignment: generate-cloud-architecture

project:
  trace_id: trace-cloud-88342
  service_name: NotificationService
  environment: Production
  tenant_id: tenant-42
  agent_version: 1.1.0

inputs:
  solution_architecture_url: https://.../solution-architecture.md
  resource_configuration_url: https://.../resource-config.yaml
  field_retention_map_url: https://.../retention-map.yaml
  latency_map_url: https://.../latency-map.json
  observability_policy_url: https://.../observability-policy.yaml
  cloud_preference_url: https://.../cloud-preference.yaml
  prohibited_regions_url: https://.../prohibited-regions.yaml

settings:
  output_format: [yaml, json, mmd]
  inject_otel: true
  fallback_cloud_provider: azure
  fallback_strategy: latency-first
  generate_mermaid_diagram: true

📁 Input Sections¶

🔷 `project`¶

Field	Description
`trace_id`	Unique identifier used for span tracing, rollback, and artifact tagging
`service_name`	Logical name of the service being planned
`environment`	Target stage (Dev, Staging, Production)
`tenant_id`	Tenant context (optional in shared infrastructure mode)
`agent_version`	Cloud Architecture Agent version to ensure backward-compatible behavior

📁 `inputs`¶

Key	Purpose
`solution_architecture_url`	Describes the target cloud footprint and services
`resource_configuration_url`	Indicates preferred regions, burstability, criticality
`field_retention_map_url`	Drives residency rules (e.g., EU-only)
`latency_map_url`	Used to determine proximity-based region decisions
`observability_policy_url`	Used to generate OTEL exporter maps
`cloud_preference_url` (optional)	Declares tenant/cloud team’s preferred cloud and region
`prohibited_regions_url` (optional)	Lists restricted zones due to legal, policy, or SLA reasons

⚙️ `settings`¶

Key	Description
`output_format[]`	Controls generated artifacts: YAML, JSON, Mermaid
`inject_otel`	Enables regional OTEL configuration generation
`fallback_cloud_provider`	Used if no match found or latency too high
`fallback_strategy`	Decides between latency-first, cost-first, or compliance-first fallback
`generate_mermaid_diagram`	If true, emits `cloud-strategy.mmd`

📘 Minimal Input Prompt Example¶

assignment: generate-cloud-architecture

project:
  trace_id: trace-cloud-55291
  service_name: UserService
  environment: Staging

inputs:
  resource_configuration_url: https://.../user-service/resource-config.yaml
  latency_map_url: https://.../shared/latency-map.json

settings:
  output_format: [yaml, mmd]
  fallback_cloud_provider: azure

✅ Validation Rules¶

Rule	Description
`trace_id`, `service_name`, and `environment` are mandatory	✅
At least one cloud region must be inferable	✅
`latency_map_url` and `resource_configuration_url` must be present	✅
`fallback_cloud_provider` must be from [azure, aws, gcp]	✅
If compliance constraint exists → fallback must not violate it	✅

📤 Output Expectations Overview¶

The Cloud Architecture Agent produces a region-aware, compliance-aligned, and cloud-provider-optimized blueprint for each service and environment.
These outputs enable infrastructure provisioning, failover configuration, DevOps orchestration, observability wiring, and cross-cloud scaling.

All outputs are machine-readable, traceable, and policy-conformant.

📦 Expected Output Artifacts¶

Artifact	Format	Purpose
`cloud-region-map.yaml`	YAML	Maps service → region → cloud provider
`replication-strategy.yaml`	YAML	Declares redundancy: GRS, ZRS, active-passive, etc.
`zone-capacity-map.yaml`	YAML	Matches service classes to tiered regions
`region-constraints.yaml`	YAML	Lists allowed and forbidden regions
`cloud-strategy.mmd`	Mermaid	Visual topology of regions, failover paths, providers
`cloud-metadata.json`	JSON	Output trace metadata, regions, compliance tags
`otel-agent-config.yaml`	YAML	Adds regional OTEL exporters
`CloudArchitecturePlanPublished`	JSON Event	Lifecycle signal to downstream agents

🧾 Example: `cloud-region-map.yaml`¶

service: NotificationService
environment: Production
cloud_targets:
  - provider: azure
    primary_region: eastus2
    failover_region: centralus
    zones: [1, 2, 3]
  - provider: aws
    fallback_region: us-west-2
    active: false

🧾 Example: `replication-strategy.yaml`¶

replication:
  type: active-active
  strategy: zone-redundant
  failover:
    ttl: 15m
    trigger: latency > 120ms or zone-down
  storage: GRS
  compute: multi-region autoscale

🧾 Example: `region-constraints.yaml`¶

allowed_regions:
  - eastus2
  - westeurope
forbidden_regions:
  - chinaeast2
  - usgovvirginia
compliance_scope: GDPR

🧾 Example: `zone-capacity-map.yaml`¶

zones:
  - region: eastus2
    class: high-performance
    cost_tier: medium
    latency_score: 9
  - region: westeurope
    class: standard
    cost_tier: low
    latency_score: 7
  - region: us-west-2
    class: burstable
    cost_tier: very-low
    latency_score: 11

📈 Example: `cloud-metadata.json`¶

{
  "trace_id": "trace-cloud-55282",
  "service": "NotificationService",
  "environment": "Production",
  "primary_region": "eastus2",
  "failover_region": "centralus",
  "provider": "azure",
  "agent_version": "1.1.0",
  "replication": "GRS",
  "compliance": "GDPR",
  "generated_at": "2025-05-02T03:08:00Z"
}

📢 Example: `CloudArchitecturePlanPublished` Event¶

{
  "event": "CloudArchitecturePlanPublished",
  "trace_id": "trace-cloud-55282",
  "service": "NotificationService",
  "environment": "Production",
  "outputs": {
    "region_map": "cloud-region-map.yaml",
    "replication": "replication-strategy.yaml",
    "metadata": "cloud-metadata.json"
  },
  "timestamp": "2025-05-02T03:08:00Z"
}

✅ Output Validation Checklist¶

Rule	Description	Enforced
`trace_id`, `agent_version`, `environment`, and `service_name` present	✅
At least one cloud provider and region selected	✅
Forbidden regions excluded	✅
Failover region exists for all production deployments	✅
If `inject_otel: true`, OTEL exporters per region must be defined	✅
Mermaid diagram generated if requested	✅

🧠 Memory Strategy Overview¶

The Cloud Architecture Agent maintains both short-term (session) memory and long-term semantic memory to ensure:

Consistent region selection across services and environments
Avoidance of deployment drift
Compliance with historical decisions
Optimized fallback and scaling plans
Traceable region-to-service lineage

🕐 Short-Term Memory (Per Execution)¶

Key	Purpose
`trace_id`	Used to tag all spans, outputs, and events
`service_name`, `environment`	Used in naming, regional grouping, metadata
`cloud_targets[]`	Cached provider selection during decision cycle
`region_plan`	Contains primary, failover, fallback regions during run
`latency_profile`	Measured latency between candidate regions
`compliance_flags`	Indicates whether GDPR, HIPAA, or FedRAMP rules apply
`generated_artifacts[]`	Tracks what outputs were emitted in the run
`violation_state`	Stores compliance or zone error messages (if any)

🧠 Long-Term Memory (Semantic Kernel Backed)¶

🌍 1. Region/Service History¶

Memory	Purpose
Last known region → service mappings	Prevents accidental drift
Zone pairing groups	Enables region pairing reuse across services
Previous fallback success history	Optimizes failover strategy for reliability and cost
OTEL exporter performance history	Helps reuse known-good observability paths

🛡️ 2. Compliance Rules¶

Memory	Use
Region classification: `safe`, `restricted`, `sovereign`	Drives initial and fallback region decisioning
Past violations and overrides	Avoids known violations or forces reapproval
Data protection class → region group	Ensures services stay within approved locations

☁️ 3. Multi-Cloud Behavior Memory¶

Memory	Use
Cloud provider fallback order (Azure > AWS > GCP)	Auto-applied unless explicitly overridden
Hybrid environment aliases	Maps `edge-` and `onprem-` to cloud-fallback regions
Platform-wide cloud quota metadata (optional)	Used to balance workloads and recommend redistributions

📍 4. Observability Path Memory¶

OTEL Exporter	Linked Services
`http://otel-eastus2:4317`	Used by 11 services → auto-selected if no better match
`https://otel-eu.connectsoft.dev`	Used for GDPR-bound services
Last used per region	Used to infer exporter in enriched `otel-agent-config.yaml`

🧾 Example: Memory Snapshot¶

{
  "trace_id": "trace-cloud-44110",
  "service": "InvoiceService",
  "primary_region": "westeurope",
  "failover_region": "northeurope",
  "compliance": "GDPR",
  "multi_cloud_strategy": "Azure primary, AWS backup",
  "otel_exporter_used": "https://otel-eu.connectsoft.dev",
  "fallback_triggered": false
}

✅ Memory Benefits¶

Benefit	Outcome
🚫 Drift prevention	Ensures services don’t silently move between zones or clouds
🧠 Intelligent fallback	Remembers which regions worked reliably under stress
🛡️ Compliance enforcement	Respects prior overrides, avoids repeated violations
📈 Span continuity	Retains OTEL and region tracing consistency
☁️ Balanced cloud usage	Guides multi-cloud distribution across tenants/services

✅ Validation and Correction Overview¶

The Cloud Architecture Agent applies rigorous validation logic to ensure all output decisions are:

Latency-optimized
Compliant with residency and region policies
Fail-safe (with valid failover and replication paths)
Traceable and deterministic
Recoverable on failure via fallback strategies

Auto-correction and event escalation mechanisms ensure safe resolution when misalignment occurs.

🔍 Validation Phases¶

1️⃣ Region and Provider Validation¶

Rule	Enforcement
At least one valid primary region must be selected	✅ Required
Selected regions must not appear in `prohibited-regions.yaml`	✅ Enforced
Fallback regions must differ from primary and reside in a distinct fault domain	✅ Recommended
Cloud provider must be supported (`azure`, `aws`, `gcp`, `hybrid`)	✅ Fallback: `azure`

2️⃣ Compliance Validation¶

Rule	Enforcement
GDPR, HIPAA, FedRAMP constraints must be met if declared	✅
Sovereign workloads (e.g., GovCloud) must use approved zones only	✅
Storage replication must align with `field-retention-map.yaml`	✅
Violations must emit `CloudComplianceViolation` and block plan promotion	✅

3️⃣ Observability and OTEL Checks¶

Rule	Enforcement
If `inject_otel: true` → at least one OTLP endpoint must be assigned per region	✅
Missing exporter triggers fallback to known regional default (e.g., `otel-eastus2`)	✅
`otel-agent-config.yaml` must be enriched with region mapping	✅

4️⃣ Failover and Replication Strategy Validation¶

Rule	Enforcement
At least one failover region is required for Production	✅
Replication type must be valid (GRS, ZRS, LRS)	✅
Active-active only allowed for `critical` service class	✅
Invalid replication triggers fallback to `GRS` + warning	✅

🔁 Auto-Correction Logic¶

Condition	Correction Applied
Forbidden region selected	Replace with lowest-latency allowed neighbor
Missing region in config	Use default from latency map + cloud preference
OTEL exporter not defined	Inject default exporter (`otel-central`, `otel-eu`)
No replication type defined	Default to `ZRS` for Dev, `GRS` for Prod
Residency mismatch	Downgrade to fallback plan + emit violation event

📢 Blocking Events & Soft Failures¶

Condition	Action
No compliant region available	Emit `CloudComplianceViolation`, block output
Trace ID or region omitted in output	Emit `CloudArchitecturePlanBlocked`, skip publish
Replication not defined + critical service	Emit warning + fallback, retry plan resolution
Failover == primary	Force failover reassignment or emit critical warning

📈 Spans Emitted¶

Span	Trigger
`region_resolved`	Region successfully assigned
`compliance_passed` / `compliance_failed`	Policy check outcomes
`replication_mapped`	Replication model finalized
`otel_exporter_assigned`	Exporters inserted for tracing
`cloud_strategy_published`	Final plan ready for downstream agents

✅ Summary of Safety and Recovery¶

Risk	Mitigation
Deployment to forbidden region	Immediate block + correction
Incomplete failover path	Auto-fill from fallback policy
Missing latency map	Use internal region ranking memory
Undeclared cloud → unknown behavior	Default to Azure with OTEL + DNS support

🤝 Collaboration Overview¶

The Cloud Architecture Agent acts as a strategic coordinator across the ConnectSoft AI Software Factory, feeding region and provider decisions to all downstream agents and ensuring environment consistency, DR readiness, and compliance alignment across services.

🔼 Upstream Providers (Input Contributors)¶

Agent	Contribution
Solution Architect Agent	Overall platform region spread and cloud target strategies
Application Architect Agent	Service grouping, availability class, latency sensitivity
Security Architect Agent	Residency restrictions, identity zones, tenant-level RBAC scopes
Data Architect Agent	Field-level residency enforcement, retention policy mappings
Observability Agent	OTEL routing preferences, exporter overlays
Platform Configuration Service	Live latency maps, quota metadata, region risk scoring

🔽 Downstream Consumers (Region-Aware Behavior)¶

Agent	Consumes
Infrastructure Architect Agent	Reads `cloud-region-map.yaml`, `replication-strategy.yaml`, `zone-capacity-map.yaml` to deploy VNet, AKS, storage
DevOps Architect Agent	Uses region mappings to create CI/CD pipelines that deploy in the correct zone
Observability Agent	Injects OTEL exporters and routing from region-to-metrics backends
Rollback Executor Agent	Reads cloud region lineage from `cloud-metadata.json` to rollback infra in same regions
Compliance Monitor Agent	Analyzes `region-constraints.yaml`, `replication-strategy.yaml` to ensure adherence
Cloud Cost Optimizer Agent	Uses `zone-capacity-map.yaml` and cost tier tags to propose reallocation

📡 Published Events¶

Event	Consumer Agents
`CloudArchitecturePlanPublished`	Infra, DevOps, Observability, Compliance, Rollback
`CloudComplianceViolation`	Platform Coordinator, Compliance Dashboard
`CloudArchitecturePlanBlocked`	DevOps & Infra Agents (halts downstream provisioning)

🧠 Shared Artifacts & Integration Points¶

Artifact	Used By
`cloud-region-map.yaml`	Infrastructure, DevOps, Observability
`replication-strategy.yaml`	Infra (for GRS/ZRS/LRS setup), DevOps (test plans), Compliance
`region-constraints.yaml`	Security, Compliance Agents
`cloud-strategy.mmd`	Developer Portal, Visual CI/CD overview
`otel-agent-config.yaml`	Observability Agent enriches regional span configs

📋 Example Data Flow¶

flowchart TD
    SolutionArchitect --> CloudArchitect
    ApplicationArchitect --> CloudArchitect
    SecurityArchitect --> CloudArchitect
    DataArchitect --> CloudArchitect
    ObservabilityAgent --> CloudArchitect

    CloudArchitect --> InfrastructureArchitect
    CloudArchitect --> DevOpsArchitect
    CloudArchitect --> ObservabilityAgent
    CloudArchitect --> RollbackExecutor
    CloudArchitect --> ComplianceMonitor

Hold "Alt" / "Option" to enable pan & zoom

📦 Traceability Tags Used by Consumers¶

All output artifacts include:

metadata:
  trace_id: trace-cloud-98871
  service_name: NotificationService
  environment: Staging
  agent_version: 1.1.0
  generated_on: 2025-05-02T03:22:00Z

This allows every connected agent to trace decisions to this Cloud Architecture Agent cycle.

✅ Collaboration Impact Summary¶

Agent	Enabled By
Infrastructure Architect	Cloud-aware provisioning
DevOps Architect	Region-specific deployment and testing
Observability Agent	OTEL exporter placement
Compliance Monitor	Residency + risk validation
Rollback Executor	Safe revert to prior region configuration

📡 Observability & Oversight¶

The Cloud Architecture Agent integrates traceable, observable, and auditable behaviors into every decision it makes.
Each generated plan is:

Span-traced using OpenTelemetry
Metadata-tagged with traceability keys
Versioned per agent release
Event-published to downstream consumers
Validatable against compliance and residency policies

📈 OpenTelemetry Span Emission¶

Span Name	Description
`region_resolved`	Fired once the primary and failover regions are chosen
`compliance_passed` / `compliance_failed`	Indicates whether residency constraints are met
`replication_mapped`	GRS/ZRS/LRS decision attached to a region or environment
`cloud_strategy_published`	Lifecycle success span — includes output artifact hashes
`otel_exporter_assigned`	Fired per region → OTEL configuration generated

Each span includes:

trace_id
service_name
environment
agent_version
duration_ms
region_count, cloud_provider
compliance_status
fallback_triggered (true/false)

📢 Lifecycle Events Emitted¶

Event	Trigger
`CloudArchitecturePlanPublished`	Plan validated and all artifacts successfully generated
`CloudComplianceViolation`	Region or replication decision violates regulatory or residency constraint
`CloudArchitecturePlanBlocked`	Failed validation, required artifact missing, or no safe region found

📊 Dashboards & Trace Visualizations¶

Dashboard Panel	Description
Region usage heatmap	Frequency of selected regions by class and environment
OTEL exporter success rate	Percentage of agents that adopted generated OTEL configs
Compliance pass/fail chart	History of region violations over time
Latency model mapping	Visualizes average latency across selected regions
Strategy lineage viewer	Mermaid-to-graph output mapping changes between versions

✅ Auditable Metadata in Outputs¶

All artifacts include trace metadata to support runtime inspection and postmortem audits:

metadata:
  trace_id: trace-cloud-88819
  agent_version: 1.1.0
  generated_on: 2025-05-02T03:30:00Z
  compliance: GDPR
  primary_region: westeurope
  fallback_region: northeurope

♻️ Rollback & Drift Awareness¶

Drift detection supported by comparing cloud-metadata.json to last known plan
Rollback Executor Agent uses region lineage to revert to previous deployment-ready state
Future integrations may emit CloudArchitecturePlanDrifted if changes are unapproved or unaligned

📦 Final Output Recap¶

Artifact	Purpose
`cloud-region-map.yaml`	Canonical service-to-region mapping
`replication-strategy.yaml`	Redundancy and failover logic
`region-constraints.yaml`	Residency + restriction enforcement
`zone-capacity-map.yaml`	Cost and performance classification
`cloud-metadata.json`	Full metadata trace of the run
`otel-agent-config.yaml`	Region-based tracing exporters
`cloud-strategy.mmd`	Visual map of region and cloud layout
`CloudArchitecturePlanPublished`	Traceable event to downstream agents

✅ Agent Impact Summary¶

Capability	Delivered
🌍 Region & zone selection	✅
☁️ Multi-cloud support	✅
🛡️ Residency and compliance enforcement	✅
🔁 Replication & failover planning	✅
📈 OTEL observability routing	✅
🧠 Traceability and memory	✅
📢 Lifecycle event emission	✅
📊 Audit + dashboard integration	✅

🧭 Final Thought¶

The Cloud Architecture Agent enables ConnectSoft to scale globally, remain secure and compliant, and deliver ultra-low latency experiences — with zero manual intervention, fully traceable decisions, and maximum deployment intelligence.

☁️ Cloud Architecture Agent Specification¶

🎯 Purpose¶

💡 Why This Agent Matters¶

🧠 Cloud-Aware Planning Use Cases¶

🧭 Factory Pipeline Context¶

🔁 Sample Impact Example¶

✅ Deliverables Supported by This Agent¶

📡 Scope of Influence¶

🔧 What This Agent Controls¶

🏗️ What It Does Not Control Directly¶

🌍 Cloud-Specific Considerations¶

🌐 Influence on Other Agents¶

✅ Summary¶

📋 Core Responsibilities¶

🧭 1. Region & Zone Selection¶

☁️ 2. Cloud Provider Targeting¶

🔁 3. Replication, Redundancy & Failover Strategy¶

🛡️ 4. Compliance-Aware Region Filtering¶

📊 5. Cost & Capacity Optimization¶

📈 6. Observability Hints¶

📢 7. Lifecycle Emission & Metadata¶

✅ Summary Table¶

📥 Core Inputs¶

📂 Required Input Artifacts¶

📘 Sample: resource-configuration.yaml¶

📘 Sample: field-retention-map.yaml¶

📘 Sample: latency-map.json¶

📘 Sample: cloud-preference.yaml¶

📘 Sample: prohibited-regions.yaml¶

✅ Input Validation Rules¶

🧩 Semantic Prompt Mapping¶

📤 Core Outputs¶

📦 Artifact Summary¶

🧾 Example: cloud-region-map.yaml¶

🧾 Example: replication-strategy.yaml¶

🧾 Example: region-constraints.yaml¶

🧾 Example: zone-capacity-map.yaml¶

📈 Example: cloud-metadata.json¶

📢 Example: CloudArchitecturePlanPublished (Event)¶

✅ Output Validations (Auto-Enforced)¶

🧠 Agent Knowledge Base Overview¶

📊 1. Latency & Network Proximity¶

Sample Logic:¶

🛡️ 2. Compliance & Residency Knowledge¶

☁️ 3. Cloud-Specific Capabilities¶

💰 4. Cost Tiers & Resource Classes¶

📍 5. Regional Behavior Heuristics¶

📦 6. Deployment Strategy Hints¶

🧩 Semantic Memory Mapping¶

✅ Knowledge Base Benefits¶

🔄 Agent Process Flow¶

📋 Step-by-Step Flow¶

1️⃣ Input Parsing & Validation¶

2️⃣ Cloud + Region Resolution¶

3️⃣ Failover & Replication Planning¶

4️⃣ Compliance & Residency Enforcement¶

5️⃣ Zone & Cost Optimization¶

6️⃣ Artifact Generation¶

7️⃣ Lifecycle Events + Spans¶

🧠 Diagram: Cloud Agent Flow¶

🔁 Auto-Correction & Recovery Behaviors¶

🛠️ Semantic Kernel Skills Overview¶

🔧 1. Input Interpretation & Validation Skills¶

🌍 2. Region and Cloud Selector Skills¶

🔁 3. Replication and Topology Planning¶

🛡️ 4. Compliance Enforcement & Risk Assessment¶

🗺️ 5. Artifact Writers & Topology Generators¶

📈 6. Lifecycle Events and Span Emitters¶

🧠 Semantic Match Example¶

🔁 Retry / Fallback Rules (per Skill)¶

📊 Metrics Emitted per Skill¶

🧰 Core Technologies and Platforms¶

🧠 Semantic Kernel (.NET)¶

☁️ Cloud Platforms Supported¶

🗺️ Region & Latency Sources¶

📜 Compliance & Residency Rules¶

📊 Observability and Span Routing¶

📁 Output Generation Stack¶

🧩 GitOps & CI/CD Integration¶

📐 Naming Conventions and Resource Mappings¶

📘 Sample: `resource-configuration.yaml`¶

📘 Sample: `field-retention-map.yaml`¶

📘 Sample: `latency-map.json`¶

📘 Sample: `cloud-preference.yaml`¶

📘 Sample: `prohibited-regions.yaml`¶

🧾 Example: `cloud-region-map.yaml`¶

🧾 Example: `replication-strategy.yaml`¶

🧾 Example: `region-constraints.yaml`¶

🧾 Example: `zone-capacity-map.yaml`¶

📈 Example: `cloud-metadata.json`¶

📢 Example: `CloudArchitecturePlanPublished` (Event)¶

🔷 `project`¶

📁 `inputs`¶

⚙️ `settings`¶

🧾 Example: `cloud-region-map.yaml`¶

🧾 Example: `replication-strategy.yaml`¶

🧾 Example: `region-constraints.yaml`¶

🧾 Example: `zone-capacity-map.yaml`¶

📈 Example: `cloud-metadata.json`¶

📢 Example: `CloudArchitecturePlanPublished` Event¶