@specverse/engines 4.1.0

package/assets/examples-decomposed/cloud-native-manifest.md

@@ -0,0 +1,379 @@
+# Cloud-Native Implementation Manifest
+
+This example demonstrates how to implement the enhanced e-commerce deployment specification (from `06-02-enhanced-deployment-example.specly`) using **AWS cloud-native services** for enterprise-grade, scalable production deployments.
+
+## Overview
+
+The **CloudNativeDeploymentManifest** shows how to implement logical deployment specifications using **AWS managed services** to achieve:
+- **Enterprise scalability** with auto-scaling and multi-AZ deployment
+- **High availability** with managed services and disaster recovery
+- **Security best practices** with encryption, IAM, and network isolation
+- **Operational excellence** with monitoring, logging, and automated maintenance
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                            AWS Cloud                                 │
+│  ┌─────────────────────────────────────────────────────────────────┐ │
+│  │                      Region: us-west-2                         │ │
+│  │                                                                 │ │
+│  │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │ │
+│  │  │     AZ-a    │    │     AZ-b    │    │     AZ-c    │        │ │
+│  │  │   EKS Nodes │    │   EKS Nodes │    │   EKS Nodes │        │ │
+│  │  │   Web Apps  │    │   Web Apps  │    │   Web Apps  │        │ │
+│  │  └─────────────┘    └─────────────┘    └─────────────┘        │ │
+│  │          │                   │                   │             │ │
+│  │  ┌───────▼───────────────────▼───────────────────▼──────────┐  │ │
+│  │  │              Application Load Balancer                  │  │ │
+│  │  └─────────────────────────────────────────────────────────┘  │ │
+│  │                                                                 │ │
+│  │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │ │
+│  │  │   RDS       │    │ ElastiCache │    │ CloudWatch  │        │ │
+│  │  │ Multi-AZ    │    │   Cluster   │    │ Prometheus  │        │ │
+│  │  │ PostgreSQL  │    │    Redis    │    │   Grafana   │        │ │
+│  │  └─────────────┘    └─────────────┘    └─────────────┘        │ │
+│  └─────────────────────────────────────────────────────────────────┘ │
+│                                                                       │
+│  ┌─────────────────────────────────────────────────────────────────┐ │
+│  │                      Global Services                            │ │
+│  │  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │ │
+│  │  │ CloudFront  │    │   Route 53  │    │    WAF      │        │ │
+│  │  │    CDN      │    │     DNS     │    │  Firewall   │        │ │
+│  │  └─────────────┘    └─────────────┘    └─────────────┘        │ │
+│  └─────────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Key Implementation Mappings
+
+### SpecVerse Components → AWS Services
+
+| SpecVerse Component | AWS Service | Configuration |
+|-------------------|-------------|---------------|
+| `Application` | **EKS** + **EC2** | Auto-scaling node groups, managed Kubernetes |
+| `Database` | **RDS PostgreSQL** | Multi-AZ, encrypted, automated backups |
+| `Cache` | **ElastiCache Redis** | Cluster mode, encryption, automatic failover |
+| `MonitoringStack` | **CloudWatch** + **Prometheus** | Managed Prometheus + Grafana workspaces |
+| `NetworkPolicy` | **VPC** + **Security Groups** | Private subnets, controlled ingress/egress |
+| Load Balancing | **Application Load Balancer** | SSL termination, health checks, auto-scaling |
+| CDN | **CloudFront** | Global edge locations, caching policies |
+| Security | **IAM** + **Secrets Manager** + **KMS** | Least privilege, encryption at rest/transit |
+
+## Implementation Features
+
+### 🌍 **Global Scale & Performance**
+- **Multi-AZ Deployment**: Spread across 3 availability zones
+- **CloudFront CDN**: Global content delivery with edge caching
+- **Auto Scaling**: Application and infrastructure level scaling
+- **Regional Distribution**: Primary region with DR capability
+
+### 🔒 **Enterprise Security**
+- **Encryption Everywhere**: At rest (KMS) and in transit (TLS)
+- **IAM Roles**: Least privilege access with service-specific roles
+- **Secrets Management**: AWS Secrets Manager for credentials
+- **Network Security**: VPC with private subnets and security groups
+- **Web Application Firewall**: AWS WAF for DDoS and application protection
+
+### 📊 **Comprehensive Observability**
+- **AWS CloudWatch**: Native AWS service monitoring
+- **Managed Prometheus**: EKS-integrated metrics collection
+- **Managed Grafana**: Enterprise dashboards and alerting
+- **AWS X-Ray**: Distributed tracing for microservices
+- **Performance Insights**: Database performance monitoring
+
+### ⚡ **High Availability & Resilience**
+- **Multi-AZ RDS**: Automatic failover database
+- **ElastiCache Clustering**: Redis with automatic failover
+- **EKS Multi-AZ**: Kubernetes control plane across AZs
+- **Cross-Region Backups**: Disaster recovery strategy
+- **Circuit Breakers**: Application-level resilience patterns
+
+## Generated Infrastructure
+
+### Terraform Configuration
+```hcl
+# EKS Cluster
+resource "aws_eks_cluster" "ecommerce" {
+  name     = "ecommerce-staging"
+  role_arn = aws_iam_role.eks_cluster_role.arn
+  version  = "1.28"
+
+  vpc_config {
+    subnet_ids              = aws_subnet.private[*].id
+    endpoint_private_access = true
+    endpoint_public_access  = true
+    public_access_cidrs     = ["0.0.0.0/0"]
+  }
+
+  encryption_config {
+    provider {
+      key_arn = aws_kms_key.eks.arn
+    }
+    resources = ["secrets"]
+  }
+}
+
+# RDS PostgreSQL Cluster
+resource "aws_rds_cluster" "ecommerce" {
+  cluster_identifier     = "ecommerce-postgres"
+  engine                = "postgres"
+  engine_version        = "15.4"
+  database_name         = "ecommerce"
+  master_username       = "postgres"
+  manage_master_user_password = true
+
+  vpc_security_group_ids = [aws_security_group.rds.id]
+  db_subnet_group_name   = aws_db_subnet_group.main.name
+
+  backup_retention_period = 7
+  preferred_backup_window = "03:00-04:00"
+
+  storage_encrypted = true
+  kms_key_id       = aws_kms_key.rds.arn
+
+  deletion_protection = true
+
+  performance_insights_enabled = true
+}
+
+# ElastiCache Redis Cluster
+resource "aws_elasticache_replication_group" "ecommerce" {
+  replication_group_id       = "ecommerce-cache"
+  description                = "E-commerce session cache"
+
+  node_type                  = "cache.t3.micro"
+  port                       = 6379
+  parameter_group_name       = "default.redis7"
+
+  num_cache_clusters         = 3
+  automatic_failover_enabled = true
+  multi_az_enabled          = true
+
+  subnet_group_name = aws_elasticache_subnet_group.main.name
+  security_group_ids = [aws_security_group.redis.id]
+
+  at_rest_encryption_enabled = true
+  transit_encryption_enabled = true
+  auth_token                 = random_password.redis_auth.result
+}
+```
+
+### Kubernetes Deployment
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ecommerce-web
+  namespace: ecommerce
+spec:
+  replicas: 6
+  selector:
+    matchLabels:
+      app: ecommerce-web
+  template:
+    spec:
+      containers:
+      - name: web
+        image: your-account.dkr.ecr.us-west-2.amazonaws.com/ecommerce-web:latest
+        ports:
+        - containerPort: 8080
+        resources:
+          requests:
+            memory: "512Mi"
+            cpu: "250m"
+          limits:
+            memory: "1Gi"
+            cpu: "500m"
+        env:
+        - name: DATABASE_URL
+          valueFrom:
+            secretKeyRef:
+              name: ecommerce-database-credentials
+              key: connection-string
+        - name: REDIS_URL
+          valueFrom:
+            secretKeyRef:
+              name: ecommerce-redis-credentials
+              key: connection-string
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          initialDelaySeconds: 30
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /ready
+            port: 8080
+          initialDelaySeconds: 5
+          periodSeconds: 5
+```
+
+## Cost Optimization Strategies
+
+### 🎯 **Resource Right-Sizing**
+- **Spot Instances**: Use for non-critical workloads (up to 90% savings)
+- **Reserved Instances**: 1-3 year commitments for predictable workloads
+- **Auto Scaling**: Scale down during low traffic periods
+- **Storage Optimization**: Use appropriate EBS volume types
+
+### 📈 **Monitoring & Alerts**
+- **Cost Anomaly Detection**: AWS Cost Explorer alerts
+- **Resource Utilization**: CloudWatch metrics and recommendations
+- **Rightsizing Recommendations**: AWS Compute Optimizer
+- **Unused Resource Detection**: AWS Trusted Advisor
+
+## Deployment Strategy
+
+### 1. **Infrastructure Provisioning**
+```bash
+# Initialize Terraform
+terraform init
+terraform plan -var-file="production.tfvars"
+terraform apply
+
+# Configure kubectl
+aws eks update-kubeconfig --region us-west-2 --name ecommerce-staging
+```
+
+### 2. **Application Deployment**
+```bash
+# Deploy using Helm
+helm repo add ecommerce ./helm-charts
+helm upgrade --install ecommerce ecommerce/ecommerce \
+  --namespace ecommerce \
+  --create-namespace \
+  --values values-production.yaml
+
+# Configure monitoring
+helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
+helm upgrade --install monitoring prometheus-community/kube-prometheus-stack \
+  --namespace monitoring \
+  --create-namespace
+```
+
+### 3. **Security Hardening**
+```bash
+# Apply security policies
+kubectl apply -f security/network-policies.yaml
+kubectl apply -f security/pod-security-standards.yaml
+
+# Configure service mesh (optional)
+istioctl install --set values.pilot.env.EXTERNAL_ISTIOD=false
+kubectl label namespace ecommerce istio-injection=enabled
+```
+
+## AI Implementation Guidance
+
+The manifest provides **comprehensive guidance** for:
+- **Infrastructure as Code**: Terraform best practices for AWS
+- **Security Hardening**: Multi-layered security implementation
+- **Observability Setup**: Complete monitoring and alerting stack
+- **High Availability**: Multi-AZ and cross-region strategies
+- **Cost Management**: Optimization strategies and monitoring
+- **Compliance**: AWS Well-Architected Framework alignment
+- **GitOps Integration**: CI/CD pipeline configuration
+- **Disaster Recovery**: Backup and restore procedures
+
+This implementation demonstrates how SpecVerse **manifests enable enterprise-grade deployments** by bridging logical specifications with cloud-native infrastructure, providing teams with production-ready, scalable, and secure deployment strategies.
+
+## Diagrams
+
+<div className="diagram-generated">
+
+### Technology Stack
+
+<Mermaid chart={`
+graph TB
+  %% Manifest Mapping
+
+  subgraph database_layer["🗄️ DATABASE"]
+    direction LR
+    tech_postgresql_rds("postgresql<br>rds<br>vlatest")
+    tech_redis_elasticache("redis<br>elasticache<br>vlatest")
+  end
+
+  subgraph infrastructure_layer["🏗️ INFRASTRUCTURE"]
+    direction LR
+    tech_kubernetes_eks("kubernetes<br>eks<br>vlatest")
+    tech_aws_alb("aws<br>alb<br>vlatest")
+  end
+
+
+  style tech_postgresql_rds fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
+  style tech_redis_elasticache fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
+  style tech_kubernetes_eks fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style tech_aws_alb fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+`}/>
+
+### Capability Bindings
+
+<Mermaid chart={`
+graph LR
+  %% Manifest Mapping
+
+  subgraph capabilities_layer["🎯 CAPABILITIES"]
+    direction TB
+    cap_0{{"web.*<br>(1 impl)"}}
+    cap_1{{"database.*<br>(1 impl)"}}
+    cap_2{{"cache.*<br>(1 impl)"}}
+    cap_3{{"routing.*<br>(1 impl)"}}
+  end
+
+  impl_CloudNativeDeploymentManifest_CloudWebApplication("CloudNativeDeploymentManifest.CloudWebApplication")
+  impl_CloudNativeDeploymentManifest_CloudDatabase("CloudNativeDeploymentManifest.CloudDatabase")
+  impl_CloudNativeDeploymentManifest_CloudCache("CloudNativeDeploymentManifest.CloudCache")
+  impl_CloudNativeDeploymentManifest_CloudLoadBalancer("CloudNativeDeploymentManifest.CloudLoadBalancer")
+
+
+  %% Relationships
+  cap_0 -->|"binds to"| impl_CloudNativeDeploymentManifest_CloudWebApplication
+  cap_1 -->|"binds to"| impl_CloudNativeDeploymentManifest_CloudDatabase
+  cap_2 -->|"binds to"| impl_CloudNativeDeploymentManifest_CloudCache
+  cap_3 -->|"binds to"| impl_CloudNativeDeploymentManifest_CloudLoadBalancer
+
+  style cap_0 fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudWebApplication fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style cap_1 fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudDatabase fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style cap_2 fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudCache fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style cap_3 fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudLoadBalancer fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+`}/>
+
+### Manifest Mapping
+
+<Mermaid chart={`
+graph LR
+  %% Manifest Mapping
+
+  subgraph manifests_layer["📋 MANIFESTS (Implementation Mapping)"]
+    direction TB
+    manifest_CloudNativeDeploymentManifest{{"CloudNativeDeploymentManifest<br>v1.0.0<br>Types: 4 | Behaviors: 2"}}
+  end
+
+  subgraph implementation_layer["🔧 IMPLEMENTATION (Technology)"]
+    direction TB
+    impl_CloudNativeDeploymentManifest_CloudWebApplication("CloudWebApplication<br>kubernetes / eks")
+    impl_CloudNativeDeploymentManifest_CloudDatabase("CloudDatabase<br>postgresql / rds")
+    impl_CloudNativeDeploymentManifest_CloudCache("CloudCache<br>redis / elasticache")
+    impl_CloudNativeDeploymentManifest_CloudLoadBalancer("CloudLoadBalancer<br>aws / alb")
+  end
+
+
+  %% Relationships
+  manifest_CloudNativeDeploymentManifest -->|"implements"| impl_CloudNativeDeploymentManifest_CloudWebApplication
+  manifest_CloudNativeDeploymentManifest -->|"implements"| impl_CloudNativeDeploymentManifest_CloudDatabase
+  manifest_CloudNativeDeploymentManifest -->|"implements"| impl_CloudNativeDeploymentManifest_CloudCache
+  manifest_CloudNativeDeploymentManifest -->|"implements"| impl_CloudNativeDeploymentManifest_CloudLoadBalancer
+
+  style manifest_CloudNativeDeploymentManifest fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudWebApplication fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudDatabase fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudCache fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+  style impl_CloudNativeDeploymentManifest_CloudLoadBalancer fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
+`}/>
+
+</div>

package/assets/examples-decomposed/cloud-native-manifest.specly

@@ -0,0 +1,60 @@
+manifests:
+  CloudNativeDeploymentManifest:
+    specVersion: "3.5.0"
+    name: "CloudNativeDeploymentManifest"
+    description: "Cloud-native implementation manifest for AWS EKS deployment"
+    version: "1.0.0"
+
+    deployment:
+      deploymentSource: "./06-01-basic-deployment.specly"
+      deploymentName: "basicWebApplication"
+
+    defaultMappings:
+      controller: "CloudWebApplication"
+      storage: "CloudDatabase"
+
+    capabilityMappings:
+      - capability: "web.*"
+        instanceFactory: "CloudWebApplication"
+
+      - capability: "database.*"
+        instanceFactory: "CloudDatabase"
+
+      - capability: "cache.*"
+        instanceFactory: "CloudCache"
+
+      - capability: "routing.*"
+        instanceFactory: "CloudLoadBalancer"
+
+    instanceMappings:
+      - instanceName: "webApplicationController"
+        instanceFactory: "CloudWebApplication"
+
+      - instanceName: "loadBalancerInstance"
+        instanceFactory: "CloudLoadBalancer"
+
+    configuration:
+      # Cloud-specific extensions
+      cloudProvider: "aws"
+      region: "us-east-1"
+      availabilityZones: ["us-east-1a", "us-east-1b", "us-east-1c"]
+
+      networking:
+        vpc: "vpc-0123456789abcdef0"
+        subnets:
+          public: ["subnet-0123456789abcdef0", "subnet-0123456789abcdef1"]
+          private: ["subnet-0123456789abcdef2", "subnet-0123456789abcdef3"]
+
+      security:
+        iamRoles:
+          eksClusterRole: "arn:aws:iam::123456789012:role/EKSClusterRole"
+          eksNodeRole: "arn:aws:iam::123456789012:role/EKSNodeRole"
+        kmsKeys:
+          ebs: "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
+          rds: "arn:aws:kms:us-east-1:123456789012:key/87654321-4321-4321-4321-210987654321"
+
+      monitoring:
+        cloudWatch: true
+        prometheusOperator: true
+        grafana: true
+        alertManager: true

package/assets/examples-decomposed/docker-compose-manifest.example.yaml

@@ -0,0 +1,8 @@
+title: "Docker Compose Deployment Manifest"
+description: "Docker Compose implementation manifest for local and staging deployment"
+difficulty: intermediate
+concepts: [manifests, docker-compose, deployment]
+prerequisites: []
+category: deploy
+order: 4
+companionFiles: [docker-compose-manifest.md]