write-rich-descriptions

name	write-rich-descriptions
description	Use metadata for system models (business/technical context) and markdown tables for deployment models (infrastructure specs). Makes models queryable and self-documenting.

Write Rich Descriptions

Use this skill to create comprehensive descriptions for elements. Choose the appropriate format based on context:

• System Models (system-model.c4): Use metadata { } blocks for structured, queryable business/technical data
• Deployment Models (deployment.c4): Use Markdown tables in descriptions for infrastructure specs (network interfaces first)

Prerequisite: Element has been created. See create-element or model-deployment for basic structure.

---

System Model: Using Metadata Blocks

For containers and components in system-model.c4, use structured metadata { } blocks. This makes your architecture queryable and enables tooling/reporting that traditional descriptions cannot support.

Advantages:

• Structured data accessible via LikeC4 API
• Filterable: Find all services with tags: ['backend']
• Queryable: Group by team, framework, regions
• Reportable: Generate compliance/dependency reports
• Version-controlled: Easy to track changes

Metadata Format

model {
  uploadService = Container_Service 'Upload Service' {
    #backend #microservice #critical
    technology 'Node.js / Express'
    
    link https://docs.company.com/upload-api 'API Documentation'
    link https://wiki.company.com/runbooks/upload-service 'Runbook'
    link https://github.com/company/upload-service 'Source Code'
    
    description """
      Handles file uploads and validates content before 
      queuing for async processing.
      
      **Responsibilities:**
      - Receive multipart file uploads
      - Fail-fast validation (size, type, malware scan)
      - Queue validated files for processing
    """
    
    metadata {
      team 'Platform'
      team_contact '[e-mail]'
      owner '[e-mail]'
      framework 'Node.js'
      framework_version '18.0'
      language 'JavaScript'
      sla '99.9%'
      rto '5 minutes'
      rpo '1 hour'
      compliance_tags ['PCI', 'SOC2']
      contact_channels ['[e-mail]', '#platform-team']
    }
  }
}

Metadata Best Practices

Links: Use link property for external resources (rendered in diagrams)

element MyService {
  link https://docs.company.com/api 'API Documentation'
  link https://github.com/org/repo 'Source Code'
  link https://grafana.company.com/d/service 'Dashboard'
  link ../src/service/index.ts#L1-L50 'Implementation'
  
  description """
    Service description here.
  """
}

Single values: Use simple key-value pairs

metadata {
  team 'Backend Team'
  sla '99.9%'
  owner '[e-mail]'
}

Multiple values: Always use arrays for lists (explicit syntax)

metadata {
  // Don't duplicate tags already on element with #tag syntax
  compliance_tags ['PCI', 'SOC2', 'HIPAA']  // Additional classification, not duplicating #critical
  regions ['us-east-1', 'eu-west-1']
  owners ['[e-mail]', '[e-mail]']
  dependencies ['database', 'queue', 'cache']
  contact_channels ['[e-mail]', '#team-slack']
}

Avoid duplication: Don't repeat model-level properties or relationship-derived data

// ❌ Bad - duplicating tags and ports
element MyService {
  #backend #critical
  metadata {
    tags ['backend', 'critical']  // Already on element!
    port '443'  // Derived from HTTPS relationship
  }
}

// ✅ Good - only additional metadata
element MyService {
  #backend #critical
  metadata {
    team 'Platform'
    sla '99.9%'
    compliance_tags ['SOC2']  // Different from architectural tags
  }
}

Group related values: Combine related fields into arrays when meaningful

metadata {
  // Group contact methods
  contact_channels ['[e-mail]', '#platform-team', '[phone]']
  
  // Group compliance requirements
  compliance_tags ['PCI', 'SOC2', 'HIPAA']
  
  // Group deployment regions
  regions ['us-east-1', 'us-west-2', 'eu-west-1']
}

Structured data: Use YAML/JSON as string values (use triple quotes ''')

metadata {
  slo_config '''
    availability: 99.9%
    latency_p99: 200ms
    error_rate: 0.1%
  '''
  
  deployment_config '''
    {
      "replicas": 3,
      "cpu": "2",
      "memory": "4Gi",
      "env": "production"
    }
  '''
}

Querying Metadata (for tooling)

Metadata becomes queryable via the LikeC4 API:

// Find all critical services
const critical = model.elements()
  .filter(e => {
    const tags = e.getMetadata('tags')
    return Array.isArray(tags) && tags.includes('critical')
  })

// Group by team
const byTeam = new Map()
for (const element of model.elements()) {
  const team = element.getMetadata('team')
  if (team) {
    if (!byTeam.has(team)) byTeam.set(team, [])
    byTeam.get(team).push(element)
  }
}

// Find multi-region services
const multiRegion = model.elements()
  .filter(e => {
    const regions = e.getMetadata('regions')
    return Array.isArray(regions) && regions.length > 1
  })

---

Deployment Model: Using Markdown Tables

For VMs, zones, and deployment infrastructure in deployment.c4, use Markdown tables in descriptions. This provides human-readable, at-a-glance infrastructure specifications.

Always put network interfaces (eth0, eth1) first in tables for easy readability.

Markdown Table Format for Deployment

ProdUploadVm = Node_Vm "prod-upload-vm" {
  technology 'Node.js + Docker'
  
  description """
    File upload handler and validation service
    
    **Network:**
    | Interface | Value |
    |:---------|:------|
    | eth0 | 10.1.0.12/24 |
    | eth1 | 10.4.0.12/24 (monitoring) |
    | Gateway | 10.1.0.1 |
    
    **Hardware:**
    | Property | Value |
    |:---------|:------|
    | OS | Ubuntu 22.04 LTS |
    | CPU | 2 vCPU |
    | RAM | 4 GB |
    | Disk | 100 GB SSD |
    
    **Application:**
    | Property | Value |
    |:---------|:------|
    | Service Port | 3001 |
    | Protocol | HTTP/2 |
    | Container | Docker |
    | Monitoring | Prometheus 9090 |
  """
  
  uploadApp = Node_App "Upload Service" {
    instanceOf vault.uploadService
  }
}

Key Rule: eth0, eth1, etc. always come first (makes network config immediately visible).

Container/Component Descriptions

Service Template (Containers with Metadata)

For system model containers, combine description (prose) with metadata (structured):

uploadService = Container_Service 'Upload Service' {
  #backend #microservice #critical
  technology 'Node.js / Express'
  
  link https://docs.company.com/upload-api 'API Documentation'
  link https://wiki.company.com/runbooks/upload-service 'Runbook'
  link https://github.com/company/upload-service 'Repository'
  
  description """
    Handles file uploads and validates content before queuing for processing.
    
    **Responsibilities:**
    - Receive multipart file uploads
    - Fail-fast validation (size, type, malware scan)
    - Queue validated files for async processing
    
    **Dependencies:**
    - RabbitMQ (job queue)
    - MongoDB (metadata storage)
    
    **Performance:**
    - Max upload size: 5GB
    - Response time: <2s for validation
    - Throughput: 100 requests/sec
  """
  
  metadata {
    team 'Platform'
    owner '[e-mail]'
    framework 'Node.js 18'
    sla '99.9%'
    rto '5 minutes'
    rpo '1 hour'
    contact_channels ['[e-mail]', '#platform-team']
  }
}

Component Template (Internal Modules with Metadata)

validateModule = Component 'File Validator' {
  #validation #security
  technology 'Multer + Custom validation'
  
  link https://wiki.company.com/validation-rules 'Validation Rules'
  
  description """
    Validates uploaded files against security and format policies.
    
    **Validates:**
    - File size (max 5GB)
    - MIME type whitelist
    - ClamAV virus signature
    
    **Returns:**
    - ValidationResult { isValid, reason, fileId }
  """
  
  metadata {
    owner '[e-mail]'
    complexity 'high'
    coverage '95%'  // test coverage
  }
}

Deployment/Infrastructure Descriptions

Important: The templates below are reference examples showing optional properties. Include only what's relevant to your infrastructure. Not every VM needs every property.

Zone Template with Single Table and Metadata

AppTier = Zone "Application Tier (VLAN 101: 10.1.0.0/24)" {
  description """
    Production microservices deployment zone.
    
    | Property | Value |
    |:---------|:------|
    | VLAN | 101 |
    | Network | 10.1.0.0/24 |
    | Gateway | 10.1.0.1 |
    | Monitoring Port | 9090 |
    | Capacity | 10 Gbps link to core |
  """
  
  metadata {
    vlan '101'
    network '10.1.0.0/24'
    gateway '10.1.0.1'
    monitoring_port '9090'
    capacity '10 Gbps'
    purpose 'Production microservices'
  }
}

VM Template: Single Table with eth0 First and Metadata

RULE: Always put eth0 and network interfaces at the top of the single table. Duplicate data in metadata { } for automation.

ProdUploadVm = Node_Vm "prod-upload-vm" {
  #Deployment
  technology "Node.js + Docker"
  
  description """
    File upload handler and validation service with fail-fast validation.
    
    | Property | Value |
    |:---------|:------|
    | eth0 | 10.1.0.12/24 |
    | eth1 | 10.4.0.12/24 (monitoring sideband) |
    | OS | Ubuntu 22.04 LTS |
    | CPU | 2 vCPU (2 GHz) |
    | RAM | 4 GB |
    | Disk | 100 GB SSD |
    | Container Runtime | Docker 20.10 |
    | Health Check | GET /health:3001 (30s) |
    | Logging | ELK → 10.4.0.10:5044 |
    | RTO | 5 min |
    | RPO | 1 hour |
  """
  
  metadata {
    eth0 '10.1.0.12/24'
    eth1 '10.4.0.12/24'
    os 'Ubuntu 22.04 LTS'
    cpu '2 vCPU'
    ram '4 GB'
    disk '100 GB SSD'
    container_runtime 'Docker 20.10'
    health_check 'GET /health:3001 (30s)'
    logging_endpoint '10.4.0.10:5044'
    rto '5 min'
    rpo '1 hour'
  }
  
  uploadApp = Node_App "Upload Service" {
    instanceOf vault.uploadService
  }
}

Network interfaces first because operators need to know networking immediately. Metadata duplicates table data for automation/tooling.

Use Case / Dynamic View Descriptions

views 'Use Cases' {
  dynamic view usecases_upload_flow {
    title 'Upload'
    description """
      Complete upload workflow from user action to secure storage.
      
      **Flow Steps:**
      1. User uploads file via web UI
      2. API Gateway authenticates request
      3. Upload Service validates file (fail-fast)
      4. Valid file queued to RabbitMQ
      5. Worker consumes job
      6. File scanned for viruses
      7. File encrypted with AES-256
      8. Encrypted file stored in MinIO
      9. Metadata saved to MongoDB
      
      **Failure Scenarios:**
      - Validation failure → 400 Bad Request (no queue)
      - Scan failure → Job failed, user notified
      - Storage failure → Retry logic (3x)
      
      **Performance:**
      - Sync validation: <1s
      - Async processing: <30s average
      - Full storage: <2m for 5GB file
    """
    
    customer -> browser 'Upload file'
    // ... rest of sequence
  }
}

Table Organization Tips

Select properties relevant to your infrastructure—these templates are reference examples, not checklists.

For Services/Containers (System Model with Metadata)

Use metadata { } blocks instead of tables:

metadata {
  team 'Platform Team'
  owner '[e-mail]'
  framework 'Node.js 18'
  sla '99.9%'
  regions ['us-east-1', 'eu-west-1']
  dependencies ['database', 'queue', 'cache']
}

Include what matters for your use cases: team contact, framework version, SLA requirements. Always use arrays for multiple values. Don't duplicate tags already on the element.

For Infrastructure/VMs (Deployment Model with Single Markdown Table)

Select only properties relevant to your VMs. This is a reference example—not all VMs need all properties.

RULE: Single table per element with eth0 always first

Order (when applicable):

1. Network interfaces (eth0, eth1, ...) - FIRST
2. Operating System
3. Hardware (CPU, RAM, Disk)
4. Service details (Port, Container, Health Check)
5. Operational (RTO, RPO)

Example with common properties:

| Property | Value |
|:---------|:------|
| eth0 | 10.1.0.12/24 |        ← NETWORK FIRST (always include)
| eth1 | 10.4.0.12/24 |        ← Add if multi-homed
| OS | Ubuntu 22.04 |          ← Include OS
| CPU | 2 vCPU |               ← Include if resource-constrained
| RAM | 4 GB |                 ← Include if resource-constrained
| Disk | 100 GB SSD |          ← Include if storage matters
| Container | Docker 20.10 |   ← Include if containerized
| Health Check | GET /health:3001 (30s) |  ← App health monitoring
| RTO | 5 min |                ← Include if critical
| RPO | 1 hour |               ← Include if stateful

Omit from tables:

• Service endpoints/ports (shown by relationships and instanceOf)
• Monitoring endpoints (shown by monitoring relationships)
• Tags (use #tag syntax on element)

A minimal VM might have only:

| eth0 | 10.1.0.12/24 |
| OS | Ubuntu 22.04 |
| CPU | 2 vCPU |

A database VM might have:

| eth0 | 10.2.0.10/24 |
| OS | Ubuntu 22.04 |
| CPU | 8 vCPU |
| RAM | 32 GB |
| Disk | 500 GB SSD |
| Application | PostgreSQL 14 |
| RTO | 2 min |
| RPO | 30 sec |

Best Practices

System Models: Metadata Block Structure

1. Use metadata { } for structured, queryable data in system-model.c4
2. Prose descriptions for narrative context and responsibilities
3. Single values for scalars (team, owner, framework)
4. Array values for lists (tags, regions, dependencies) — always explicit arrays
5. Group related values into arrays when meaningful (contact_channels, compliance_tags)
6. YAML/JSON strings for complex config (use triple quotes)
7. Cross-reference related elements in prose

Deployment Models: Single Table Structure

1. Single Markdown table per element (Zone, VM)
2. Network interfaces first (eth0, eth1, VLAN, Gateway)
3. Then identification (Hostname, OS)
4. Then hardware (CPU, RAM, Disk)
5. Then service (Ports, Container, Health Check)
6. Finally operational (RTO, RPO, Backup)7. Also add metadata { } with same data for automation/tooling

Deployment Model: What NOT to Include

These are already defined elsewhere — don't duplicate:

• ❌ Hostname → It's the element title in the model (e.g., ProdUploadVm = Node_Vm "prod-upload-vm")
• ❌ Gateway → Not needed for individual VMs/baremetal servers (they know their uplink)
  • Exception: Gateway belongs in zone tables (defines default route for subnet)
  • Exception: Gateway in metadata for edge cases (multi-homed, policy routing)
• ❌ Firewall Entry/Exit rules → Defined by diagram arrows between zones/elements
• ❌ Monitoring Links → Defined by diagram relationships to monitoring systems
• ❌ Backup mechanisms → Separate infrastructure concern

Good pattern:

• Zone table: Include gateway (it's the zone's default route)
• VM table: Omit gateway (VM is already in its zone; gateway is implicit)
• Diagram: Shows firewall/monitoring/backup flows

Example Zone vs VM:

// ZONE - includes gateway (defines subnet routing)
AppTier = Zone "Application Tier (VLAN 101: 10.1.0.0/24)" {
  description """
    | VLAN | Network | Gateway | Monitoring Port |
    |------|---------|---------|---|
    | 101 | 10.1.0.0/24 | 10.1.0.1 | 9090 |
  """
}

// VM - omits gateway and hostname (already in model)
ProdUploadVm = Node_Vm "prod-upload-vm" {
  description """
    | eth0 | 10.1.0.12/24 |  ← Only the NIC; gateway is implicit to zone
    | CPU | 2 vCPU |
    | RTO | 5 min |
  """
}

Dual Approach: Tables + Metadata for Complete Automation

Why both?

• Markdown tables → Human operators need readable, structured specs at a glance
• Metadata { } → Automation/tooling queries for inventory, compliance, capacity planning

Example:

ProdDbVm = Node_Vm "prod-db-vm" {
  description """
    Primary database server with HA failover.
    
    | Property | Value |
    |:---------|:------|
    | eth0 | 10.2.0.10/24 |
    | eth1 | 10.4.0.10/24 |
    | OS | Ubuntu 22.04 |
    | CPU | 8 vCPU |
    | RAM | 32 GB |
    | Disk | 500 GB SSD |
    | Application | PostgreSQL 14 |
    | RTO | 2 min |
    | RPO | 30 sec |
  """
  
  metadata {
    eth0 '10.2.0.10/24'
    eth1 '10.4.0.10/24'
    os 'Ubuntu 22.04 LTS'
    cpu '8 vCPU'
    ram '32 GB'
    disk '500 GB SSD'
    app 'PostgreSQL 14'
    rto '2 min'
    rpo '30 sec'
  }
}

When to Use What

Aspect	System Model	Deployment Model
Tool	metadata { } blocks	Markdown tables in description
Queryable	Yes (via LikeC4 API)	No (text only)
Grouped	Logical (team, framework)	Operational (network, hardware)
Example	team, owner, sla, tags	eth0, CPU, RAM, RTO
File	system-model.c4	deployment.c4

Common Mistakes

❌	✅	Why
System model with tables	Metadata blocks in system model	Metadata is queryable/filterable
Multiple separate tables (Network/Hardware/Service)	Single table per element	Unified format easier to scan and maintain
Deployment tables without eth0 at top	eth0 first in single table	Operators need network info immediately
Mixed property ordering across VMs	eth0 → OS → CPU → port → RTO	Predictable structure aids scanning
Hostname in VM table	Omit—it's the element title	Redundant with model definition
Gateway in VM table	Omit—implicit to zone; use in zone table	VMs inherit zone's gateway
Metadata as strings not arrays	Use arrays: tags: ['backend', 'critical']	Enables filtering/grouping logic
No YAML/JSON for complex config	Use triple quotes for structured data	Complex data needs structure
Section headers like Network: in table	Single table without section headers	Cleaner, more maintainable format
Firewall rules in VM table	Firewall only in diagram arrows	Diagram defines topology; avoid duplication
Monitoring links in deployment table	Monitoring only in diagram relationships	Relationships define monitoring flow
Service endpoints in VM table	Service ports shown by relationships	Avoid duplicating relationship data
Tags in metadata	Use #tag syntax on element	Tags are model properties, not metadata
Deployment metadata without table	Always provide Markdown table + metadata	Tables for humans, metadata for automation

---

Related Skills

• create-element - Basic element creation (before writing description)
• model-deployment - Deployment infrastructure (describes VMs/zones)
• name-deployment-nodes - Naming conventions (referenced in descriptions)