C4 Persona Creation

Critical Requirements

•ALWAYS read likec4/model.c4 and likec4/relations.c4 before creating or editing personas
•Personas require changes in 3+ files — follow ALL steps
•ALWAYS validate with npm run validate after changes

Overview

Personas (actors) represent the different types of users who interact with the Internal Developer Portal. Each persona has specific capabilities they access and specific workflows (journeys) they follow.

Current Personas

Persona	Variable	Primary Stars
Application Developer	`developer`	starTemplates, starCatalog, starVCS, starCICD, starArtifacts
Platform Engineer	`platformEngineer`	starTemplates, integrationLayer, starResource, starCICD
Tech Lead	`techLead`	starMetrics, starQuality, starOrganization, starGRC, starCatalog
Security Engineer	`securityEngineer`	starSecurity, starGRC, starCatalog

Persona Structure in model.c4

Personas are defined at the top level of the model, outside the idp system:

model {

  developer = actor 'Developer' {
    description 'Software engineer who uses the portal for daily development workflows'
    style {
      shape person
      color amber
    }
  }

  idp = system 'Internal Developer Portal' { ... }
}

Complete Steps to Create a New Persona

Step 1: Define the actor in `model.c4`

model {
  qaEngineer = actor 'QA Engineer' {
    description 'Quality assurance engineer who validates releases and manages test environments'
    style {
      shape person
      color amber
    }
  }
}

Rules:

•Variable name: camelCase (e.g., qaEngineer)
•Kind: actor
•Style: shape person, color amber (consistent with other personas)
•Must have description

Step 2: Add capability relations in `relations.c4`

// QA Engineer → Capabilities
idp.starQuality -> qaEngineer 'provides quality dashboards' {
  navigateTo qaEngineerQualityReview
}
idp.starCICD -> qaEngineer 'provides pipeline visibility' {
  navigateTo qaEngineerTestExecution
}

Relation Pattern:

•Direction: idp.star* -> persona (star provides value TO persona)
•Include navigateTo referencing the dynamic view ID
•Each relation represents a primary interaction

Step 3: Create journey views in `views/journeys.c4`

Create at least one dynamic view for the persona:

dynamic view qaEngineerQualityReview {
  title 'QA Engineer: Quality Review'
  description 'QA Engineer reviews quality gates and test coverage for a service'

  qaEngineer -> idp 'navigates to Developer Portal' {
    notes 'QA Engineer accesses the portal to review quality metrics'
  }
  idp -> idp.starCatalog 'browses service catalog' {
    notes 'Finds the service to review'
  }
  idp.starCatalog -> idp.starQuality 'checks quality metrics' {
    notes 'Reviews code quality, test coverage, and quality gates'
  }
}

Step 4: Validate

bash

npm run validate
npm test

Checklist for New Persona

• Actor defined in model.c4 with actor kind
• Has description and style { shape person; color amber }
• At least 2-3 capability relations in relations.c4
• Each relation has navigateTo pointing to a journey view
• At least 1 dynamic journey view in views/journeys.c4
• Appears in C1 landscape view
• npm run validate passes
• npm test passes

Persona Capability Matrix

Capability	Developer	Platform Eng	Tech Lead	Security Eng
starCatalog	Yes	—	Yes	Yes
starOrganization	—	—	Yes	—
starVCS	Yes	—	—	—
starCICD	Yes	Yes	—	—
starResource	—	Yes	—	—
starArtifacts	Yes	—	—	—
starSecurity	—	—	—	Yes
starQuality	—	—	Yes	—
starMetrics	—	—	Yes	—
starTemplates	Yes	Yes	—	—
starGRC	—	—	Yes	Yes
integrationLayer	—	Yes	—	—

Workflow

•Read likec4/model.c4
•Read likec4/relations.c4
•Read likec4/views/journeys.c4
•Create actor in model.c4
•Add capability relations in relations.c4
•Create journey views in views/journeys.c4
•Validate with npm run validate