model-deployment

name	model-deployment
description	Model deployment infrastructure (environments, zones, VMs, apps) with proper hierarchy and instanceOf links. Organize zones into tiers (DMZ, App, Data, Processing) with rich descriptions including VLAN/network specifications.

Model Deployment Infrastructure

Use this skill when defining physical infrastructure in deployment.c4.

For detailed naming conventions, see name-deployment-nodes skill.

Core Requirements

1. Use shared spec node kinds - Use deployment kinds from shared/spec-deployment.c4, don't create custom ones
2. Use shared spec tags - Use tags defined in spec-deployment.c4 (#Production, #Networking, #Service, #Monitoring)
3. PascalCase variables: Use ProdApiVm not prod_api_vm in deployment
4. instanceOf (camelCase!): Link Node_App to model Container using instanceOf (NOT instanceof) with FQN
5. Parent containment: Always nest VMs within zones, zones within environments
6. Infrastructure relationships: Use https, tcp, etc. with port descriptions
7. Port format: Use "any -> 443" or "8080 -> 8080" in description blocks

Shared Spec Principle

Before creating a new deployment node kind or tag:

1. Check shared/spec-deployment.c4 for existing kinds and tags
2. Use what's already defined
3. If something is needed that's not in spec:
   • Ask user permission first
   • Suggest contributing to shared spec
   • Don't create project-specific custom kinds
   • Add to spec so all projects can use it

Core Principle: Always Show Parent Containers

Deployment hierarchy MUST show parent-child relationships:

• VMs always within zones - Never show VMs floating outside infrastructure
• Zones always within environments - Never show zones without datacenter/environment context
• Instances always within VMs - Never show services floating free of infrastructure
• This ensures infrastructure is always contextualized: "Where does this run? In what network? In what environment?"

Structure

Node_Environment (Production/Development)
  └─ Zone (VLAN/Network segment)
      └─ Node_Vm/Node_Server
          └─ Node_App (instanceOf Container from model)

Tier Organization Pattern

Organize deployment zones into logical tiers for clear responsibility separation:

Standard Tier Structure:

Production Datacenter
├── DMZ (Dmz zone) - Edge services, TLS termination
│   ├── API Gateway VM
│   └── Web Server VM
├── Application Tier (AppTier zone) - Microservices
│   ├── Service 1 VM
│   └── Service 2 VM
├── Processing Tier (ProcTier zone) - Async workers
│   ├── Queue VM
│   └── Worker VM
└── Data Tier (DataTier zone) - Persistence
    ├── Database VM
    └── Storage VM

Optional Tiers for Operations:

├── Security Tier (SecZone) - Monitoring and observability
│   └── Monitoring VM
└── Infrastructure Tier (InfraZone) - Backup and DR
    └── Backup VM

Mirror System Model Relationships in Deployment

Critical principle: For every relationship in the system model, create a corresponding deployment relationship with specific protocol/port details.

System Model → Deployment Model Mapping

System Model Relationship	Deployment Relationship	Protocol
frontend -[calls]-> api	frontendInstance -> apiInstance	HTTPS/443
api -[calls]-> service	apiInstance -> serviceInstance	HTTP or custom port
service -[async]-> queue	serviceInstance -> queueInstance	AMQP/5672, MQTT, etc.
service -[reads]-> db	serviceInstance -> dbInstance	TCP with DB port (3306, 5432, 27017)
service -[writes]-> storage	serviceInstance -> storageInstance	S3/9000, NFS, etc.

Pattern: Concrete Protocol Relationships

System model shows logical interactions:

// system-model.c4
vault.frontend -[calls]-> vault.api 'Makes API requests'
vault.api -[calls]-> vault.uploadService 'Route uploads'
vault.uploadService -[async]-> jobs 'Queue for processing'
vault.worker -[reads]-> docDB 'Fetch metadata'

Deployment model shows physical connectivity:

// deployment.c4
UserBrowser.browserApp.frontend -> Prod.Dmz.ProdApigwVm.apiApp "API requests" {
  description "any -> 443 (HTTPS)"
}

Prod.Dmz.ProdApigwVm.apiApp -> Prod.AppTier.ProdUploadVm.uploadApp "Route uploads" {
  description "443 -> 3001"
}

Prod.AppTier.ProdUploadVm.uploadApp -> Prod.ProcTier.ProdQueueVm.queueApp "Queue jobs" {
  description "3001 -> 5672 (AMQP)"
}

Prod.ProcTier.ProdWorkerVm.workerApp -> Prod.DataTier.ProdDatabaseVm.dbApp "Persist metadata" {
  description "any -> 27017 (MongoDB)"
}

Why Mirror Relationships?

1. Deployment completeness - Every logical interaction has physical implementation
2. Firewall rule derivation - Security teams can extract exact port/protocol requirements
3. Network diagram accuracy - Shows actual TCP/UDP flows between infrastructure
4. Troubleshooting - Operators know which ports to check when debugging connectivity

Common Protocol Mappings

HTTP/HTTPS Services:

• System: -[calls]->
• Deployment: -> ... { description "... -> 443 (HTTPS)" } or custom port

Message Queues:

• System: -[async]->
• Deployment: -> ... { description "... -> 5672 (AMQP)" } or other message protocol

Databases:

• System: -[reads]-> or -[writes]->
• Deployment: -> ... { description "... -> 27017 (MongoDB)" } or specific DB port

Object Storage:

• System: -[writes]-> to storage
• Deployment: -> ... { description "... -> 9000 (S3 API)" }

External APIs:

• System: -[calls]-> externalService
• Deployment: -[https]-> ... { description "any -> 443" }

Anti-Pattern: Missing Deployment Relationships

❌ Bad: System model shows relationships, deployment only shows instances

// system-model.c4
api -[calls]-> uploadService
uploadService -[async]-> queue

// deployment.c4 - INCOMPLETE!
apiApp = Node_App { instanceOf vault.api }
uploadApp = Node_App { instanceOf vault.uploadService }
// Missing: apiApp -> uploadApp relationship!

✅ Good: Every system relationship mirrored in deployment

// system-model.c4
api -[calls]-> uploadService

// deployment.c4 - COMPLETE
apiApp = Node_App { instanceOf vault.api }
uploadApp = Node_App { instanceOf vault.uploadService }
apiApp -> uploadApp "Route uploads" {
  description "443 -> 3001 (HTTP)"
}

Zone Description Template

Each zone should include VLAN, network, and connectivity details:

AppTier = Zone "Application Tier (VLAN 101: 10.1.0.0/24)" {
  description """
    Microservices deployment zone
    
    | Property | Value |
    |:---------|:------|
    | VLAN | 101 |
    | Network | 10.1.0.0/24 |
    | Gateway | 10.1.0.1 |
    | Purpose | Production microservices |
    | Firewall | DMZ → AppTier (ingress 443) |
    | Firewall | AppTier → DataTier (egress 27017) |
  """

  ProdUploadVm = Node_Vm "prod-upload-vm" { ... }
  ProdRetrievalVm = Node_Vm "prod-retrieval-vm" { ... }
}

Rich Descriptions with Infrastructure Specs

Every VM should have a Markdown table with infrastructure specifications:

ProdUploadVm = Node_Vm "prod-upload-vm" {
  #Deployment
  technology "Node.js + Docker"
  
  description """
    File upload handler and validation service
    
    | Property | Value |
    |:---------|:------|
    | Hostname | prod-upload-vm |
    | IP Address | 10.1.0.12/24 |
    | OS | Ubuntu 22.04 LTS |
    | CPU | 2 vCPU |
    | RAM | 4 GB |
    | Port | 3001 |
    | Container | Docker |
    | Monitoring | Prometheus 9090 |
  """
  
  uploadApp = Node_App "Upload Service" {
    instanceOf vault.uploadService
  }
}

Complete Multi-Tier Example

deployment {
  Prod = Node_Environment 'Production Datacenter - EU' {
    #Production
    
    // Edge security zone
    Zone Dmz "Network DMZ (VLAN 100: 10.0.0.0/24)" {
      description """
        Perimeter security zone with TLS termination
        
        | Property | Value |
        |:---------|:------|
        | VLAN | 100 |
        | Network | 10.0.0.0/24 |
        | Purpose | Edge services |
      """
      
      ProdApigwVm = Node_Vm "prod-apigw-vm" {
        technology "Kong / API Gateway"
        description """
          | IP | 10.0.0.10/24 |
          | Port | 443 |
        """
        
        apiApp = Node_App "API Gateway" {
          instanceOf vault.api
        }
      }
    }
    
    // Application services tier
    AppTier = Zone "Application Tier (VLAN 101: 10.1.0.0/24)" {
      description """
        | Property | Value |
        |:---------|:------|
        | VLAN | 101 |
        | Network | 10.1.0.0/24 |
      """
      
      ProdUploadVm = Node_Vm "prod-upload-vm" {
        description "| IP | 10.1.0.12/24 | | Port | 3001 |"
        uploadApp = Node_App "Upload Service" {
          instanceOf vault.uploadService
        }
      }
    }
    
    // Processing tier
    ProcTier = Zone "Processing Tier (VLAN 102: 10.2.0.0/24)" {
      ProdWorkerVm = Node_Vm "prod-worker-vm" {
        description "| IP | 10.2.0.15/24 |"
        workerApp = Node_App "Worker" {
          instanceOf vault.worker
        }
      }
    }
    
    // Data tier
    DataTier = Zone "Data Tier (VLAN 103: 10.3.0.0/24)" {
      ProdDatabaseVm = Node_Vm "prod-database-vm" {
        description "| IP | 10.3.0.16/24 | | Port | 27017 |"
        dbApp = Node_App "Database" {
          instanceOf vault.docDB
        }
      }
    }
  }
}

Prod.AppTier.ProdUploadVm -[https]-> Prod.DataTier.ProdDatabaseVm 'Persist metadata' {
  description "10.1.0.12 -> 10.3.0.16:27017"
}