C4 Capability Star Creation

Critical Requirements

• •ALWAYS read likec4/model.c4 before creating a new capability star
• •A new star requires changes in 5+ files — follow ALL steps below
• •ALWAYS validate with npm run validate after changes

Overview

Capability Stars are the top-level grouping mechanism in the data model. Each star represents a platform capability domain (e.g., Version Control, Security, CI/CD). Stars contain blueprints which are the actual data entities.

The current model has 13 Capability Stars:

Complete Steps to Create a New Capability Star

Step 1: Define the star in model.c4

Add the new capability inside the idp system block:

model {
  idp = system 'Internal Developer Portal' {
    starObservability = capability 'Observability' {
      description 'Monitoring, logging, tracing and alerting capabilities'
      icon bootstrap:binoculars
      style {
        color sky
      }
    }
  }
}

Rules:

• •Variable name: starCamelCase (e.g., starObservability)
• •Kind: capability
• •Style: color sky (consistent with other stars)

Step 2: Create the blueprint file

Create a new file likec4/blueprints/<star-name>.c4:

// ================================================================
// Star: Observability
// Blueprints: logPipeline, metric, trace, alert
// ================================================================

extend idp.starObservability {

  logPipeline = blueprint 'Log Pipeline' {
    description 'Represents a centralized log collection and processing pipeline'
    icon bootstrap:journal-text
    technology 'ELK Stack / Loki'
    style {
      color green
    }
  }

  // DataSource relations
  logPipeline -[dataSource]-> idp.integrationLayer.intObservability 'synced from monitoring stack' {
    #sync
  }

}

Step 3: Add integration in model.c4 (if needed)

If the star needs a new external system and/or integration:

grafana = externalSystem 'Grafana' {
  description 'Observability and monitoring platform'
  icon tech:grafana
}

idp = system 'Internal Developer Portal' {
  integrationLayer = capability 'Integration Layer' {
    intObservability = integration 'Observability Connector' {
      description 'Syncs monitoring data from Grafana/Prometheus'
      icon bootstrap:binoculars
    }
  }
}

Step 4: Add relations in relations.c4

// Actor → New Star
idp.starObservability -> developer 'provides monitoring' {
  navigateTo developerMonitoring
}

// Integration ↔ External System
idp.integrationLayer.intObservability -[syncs]-> grafana 'syncs from Grafana' { #sync }

// Integration → Blueprints
idp.integrationLayer.intObservability -[syncs]-> idp.starObservability.logPipeline 'syncs logs' { #sync }

Step 5: Add C2 container view in views/containers.c4

The star should appear in the C2 capability overview. If the view uses include *, it will be auto-included.

Step 6: Create C3 component view file views/c3/<star-name>.c4

Create a new file likec4/views/c3/observability.c4:

views {

  view starObservabilityView of idp.starObservability {
    title 'Observability Star'
    description 'Blueprints: logPipeline, metric, trace, alert'
    include *
  }

}

Step 7: (Optional) Add dynamic journey views in views/journeys.c4

Step 8: Validate

npm run validate
npm test

Checklist for New Capability Star

• • Star defined in model.c4 with capability kind
• • Blueprint file created in blueprints/<name>.c4
• • At least one blueprint defined with description and icon
• • Integration added in model.c4 (if new external system)
• • External system added in model.c4 (if needed)
• • Actor → Star relations in relations.c4
• • Integration ↔ External System syncs in relations.c4
• • Integration → Blueprint syncs in relations.c4
• • Blueprint → Integration dataSource in blueprint file
• • C2 container view updated in views/containers.c4
• • C3 component view file created in views/c3/<star-name>.c4
• • npm run validate passes
• • npm test passes

Workflow

1. •Read likec4/model.c4
2. •Read likec4/relations.c4
3. •Read likec4/views/containers.c4 and likec4/views/c3/ directory
4. •Create star in model.c4
5. •Create blueprint file in likec4/blueprints/
6. •Add relations in relations.c4
7. •Update views
8. •Validate with npm run validate