Deployment Grammar Reference

Syntax

Deployment Environment

deploymentEnvironment "<name>" {
  // deployment nodes, groups, relationships
}

Deployment Node

deploymentNode "<name>" ["description"] ["technology"] ["tags"] ["instances"] {
  // nested nodes, infrastructure nodes, groups, relationships
}

Parameters:

• name: Required, identifies the node
• description: Optional, describes the node’s purpose
• technology: Optional, specifies the technology/platform
• tags: Optional, comma-separated tags (e.g., “Server,Linux”)
• instances: Optional, number or range:
  • Numeric: "3" = exactly 3 instances
  • Range: "1..N" = auto-scaling from 1 to N
  • Range: "0..5" = from 0 to 5 instances

Infrastructure Node

infrastructureNode "<name>" ["description"] ["technology"] ["tags"] {
  // relationships, properties
}

Parameters:

• name: Required, identifies the infrastructure
• description: Optional, describes the infrastructure
• technology: Optional, specifies the technology/platform
• tags: Optional, comma-separated tags

Examples

Simple Deployment

workspace {
  model {
    deploymentEnvironment "Production" {
      deploymentNode "Web Server" "Primary server" "Ubuntu 20.04" "Server" {
      }
    }
  }
}

Auto-scaling Deployment

deploymentEnvironment "Production" {
  deploymentNode "Auto-scaling Group" "Web tier" "" "" "1..N" {
    deploymentNode "EC2 Instance" "Web server" "Amazon Linux 2" "Server"
  }
}

Nested Infrastructure

deploymentEnvironment "Production" {
  deploymentNode "AWS US-East-1" "AWS Region" "AWS" {
    deploymentNode "Availability Zone 1" {
      deploymentNode "Application Tier" "" "" "" "3" {
      }
    }
  }
}

Infrastructure Node

deploymentNode "AWS" {
  infrastructureNode "Load Balancer" "Routes traffic" "AWS ALB" "Infrastructure"
}

Child Block Syntax

Alternative to positional parameters:

deploymentNode "Server" {
  description "Web server"
  technology "Ubuntu 20.04"
  tags "Server" "Linux"
  instances "1..N"
}

Multiple Environments

workspace {
  model {
    deploymentEnvironment "Development" {
      deploymentNode "Docker" "Local dev" "Docker Desktop"
    }

    deploymentEnvironment "Production" {
      deploymentNode "AWS" "Cloud production" "AWS"
    }
  }
}

Complete Example

workspace {
  model {
    person user "User"
    softwareSystem app "Application" {
      container web "Web App" "React"
      container api "API" "Node.js"
      container db "Database" "PostgreSQL"
    }

    deploymentEnvironment "Production" {
      deploymentNode "AWS US-East-1" "AWS Region" "AWS" {

        deploymentNode "Load Balancer Tier" {
          infrastructureNode "ALB" "Application Load Balancer" "AWS ALB" "Infrastructure"
        }

        deploymentNode "Application Tier" "Auto-scaling" "" "" "1..N" {
          deploymentNode "EC2 Instance" "Web + API server" "Ubuntu 20.04" "Server" {
          }
        }

        deploymentNode "Database Tier" {
          deploymentNode "RDS Instance" "Primary DB" "PostgreSQL 13" "Database" {
          }
        }

      }
    }

    user -> app "Uses"
  }

  views {
    systemContext app {
      include *
      autoLayout lr
    }
  }
}

Instance Ranges

Syntax	Meaning	Use Case
"1"	Exactly 1 instance	Single server
"3"	Exactly 3 instances	Fixed cluster size
"1..N"	Auto-scaling from 1 to N	Cloud auto-scaling
"0..5"	Range from 0 to 5	Conditional scaling
"2..10"	Range from 2 to 10	Min/max scaling

Common Patterns

3-Tier Architecture

deploymentEnvironment "Production" {
  deploymentNode "Region" {
    deploymentNode "Presentation Tier" {
      infrastructureNode "Load Balancer"
    }
    deploymentNode "Application Tier" "" "" "" "1..N" {
    }
    deploymentNode "Data Tier" {
    }
  }
}

Multi-Region

deploymentEnvironment "Production" {
  deploymentNode "AWS US-East-1" "Primary region" "AWS" {
  }
  deploymentNode "AWS EU-West-1" "Secondary region" "AWS" {
  }
}

Microservices

deploymentEnvironment "Production" {
  deploymentNode "Kubernetes" "K8s cluster" "Kubernetes" {
    deploymentNode "Service A" "" "" "" "2..5" {
    }
    deploymentNode "Service B" "" "" "" "1..3" {
    }
  }
}

Tips

1. Empty Parameters: Use "" for empty intermediate parameters

   deploymentNode "Server" "" "Ubuntu"  // description empty, technology set

2. Tags: Separate multiple tags with commas (no spaces)

   deploymentNode "Server" "" "" "Linux,Production,Server"

3. Nesting: No depth limit on nested deployment nodes

   deploymentNode "Region" {
     deploymentNode "Zone" {
       deploymentNode "Rack" {
         deploymentNode "Server" {
         }
       }
     }
   }

4. Child Blocks: Override positional parameters

   deploymentNode "Server" "" {
     technology "Ubuntu 20.04"  // Overrides empty positional
   }

Testing

Run deployment grammar tests:

cd frontend
npm test deployment.test.ts

Expected: 20/20 tests passing ✅