Backstage Primer & Modeling Guide — Developer Portal Catalog with Linked.Archi

This guide introduces the Backstage software catalog model as formalised in Linked.Archi, explains how its concepts map to semantic assets, and demonstrates practical modeling through a worked example.

Backstage Concepts

What is Backstage?

Backstage is an open-source developer portal platform originally created by Spotify. Its Software Catalog provides a centralised registry of all software components, systems, APIs, resources, and their ownership within an organisation.

Backstage is: - Developer-centric — built for engineering teams to discover and understand services - Ownership-first — every entity has a clear owner (team/group) - API-aware — APIs are first-class citizens with provider/consumer relationships - Domain-driven — entities are grouped into business domains

"Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end." — backstage.io

Catalog Entity Types

graph TD
    subgraph Software["Software Entities"]
        Component["Component"]
        System["System"]
        API["API"]
        Resource["Resource"]
    end

    subgraph Organisational["Organisational Entities"]
        Domain["Domain"]
        User["User"]
        Group["Group"]
    end

    Component -->|"partOfSystem"| System
    Component -->|"providesAPI"| API
    Component -->|"consumesAPI"| API
    Component -->|"usesResource"| Resource
    Component -->|"ownedBy"| Group
    System -->|"belongsToDomain"| Domain
    User -->|"memberOf"| Group

    style Software fill:#B3D9FF,stroke:#333,color:#000
    style Organisational fill:#D4E6B5,stroke:#333,color:#000

Entity	What it represents
Component	A deployable unit — service, library, website, or application
System	A set of components that provide business or technical value together
API	An interface owned and maintained in the ecosystem (OpenAPI, AsyncAPI, gRPC, GraphQL)
Resource	Infrastructure used by components — databases, buckets, queues, external services
Domain	A high-level business domain grouping systems and components
User	A human user in the ecosystem
Group	A team, department, or tribe that owns entities

Relationships

Relationship	From → To	Meaning
ownedBy	Any → Group	Entity is owned by a team
partOfSystem	Component → System	Component belongs to a system
providesAPI	Component → API	Component exposes an API
consumesAPI	Component → API	Component depends on an API
usesResource	Component → Resource	Component uses infrastructure
belongsToDomain	Any → Domain	Entity is part of a business domain
memberOf	User → Group	User belongs to a team

Lifecycle

Components carry a lifecycle property: experimental → production → deprecated.

Semantic Assets

Asset Set

modelingLanguages/backstage/
├── backstage-metamodel.ttl             ← Entry point: arch:Metamodel
├── backstage-onto.ttl                  ← OWL ontology (7 elements, 7 relationships)
├── backstage-tax.ttl                   ← SKOS taxonomy
├── backstage-shapes.ttl                ← SHACL validation
├── backstage-viewpoints.ttl            ← 5 viewpoints
├── backstage-reference-data.ttl        ← Lifecycle states, component types, API types
├── backstage-presentation-contexts.ttl ← Developer, Architect, Stakeholder themes
└── backstage-deliverable-templates.ttl ← Document templates

Concept-to-Asset Mapping

Backstage Concept	Semantic Representation	File
Entity types (Component, System, etc.)	owl:Class rdfs:subClassOf arch:Element	backstage-onto.ttl
Relationships (ownedBy, providesAPI, etc.)	Three-declaration pattern	backstage-onto.ttl
Lifecycle, component types, API types	skos:ConceptScheme	backstage-reference-data.ttl
Validation (ownership required, etc.)	sh:NodeShape	backstage-shapes.ttl
Viewpoints	arch:Viewpoint	backstage-viewpoints.ttl

Cross-Language Integration

Backstage entities map naturally to ArchiMate and C4:

Backstage	ArchiMate 4.0	C4
bs:Component	am4:ApplicationComponent	c4:Container or c4:Component
bs:System	(group of components)	c4:SoftwareSystem
bs:API	am4:ApplicationInterface	—
bs:Resource	am4:Node / am4:Artifact	c4:DeploymentNode
bs:Group	am4:Role	—

Worked Example: PayFlow (Fintech Platform)

Prerequisites

core/core-onto.ttl
modelingLanguages/backstage/backstage-onto.ttl
modelingLanguages/backstage/backstage-tax.ttl
modelingLanguages/backstage/backstage-shapes.ttl
modelingLanguages/backstage/backstage-viewpoints.ttl
modelingLanguages/backstage/backstage-reference-data.ttl
modelingLanguages/backstage/backstage-metamodel.ttl

About PayFlow

PayFlow is a fintech platform providing payment processing, merchant onboarding, and financial reporting as a service. The engineering organisation is structured into domain-aligned squads using Backstage as their developer portal.

The complete, validatable example model is available at examples/payflow/payflow-model.ttl.

Model File Header

@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix arch:    <https://meta.linked.archi/core#> .
@prefix bs:      <https://meta.linked.archi/backstage/onto#> .
@prefix :        <https://meta.linked.archi/examples/payflow/> .

:PayFlowModel
    a                          arch:Model ;
    skos:prefLabel             "PayFlow — Backstage Catalog Model"@en ;
    arch:modelConformsToMetamodel <https://meta.linked.archi/backstage/metamodel#Backstage> ;
    dcterms:created            "2025-06-27"^^xsd:date ;
.

Element Patterns

## Domains
:PaymentsDomain a bs:Domain ; skos:prefLabel "Payments"@en .
:MerchantDomain a bs:Domain ; skos:prefLabel "Merchant Services"@en .
:PlatformDomain a bs:Domain ; skos:prefLabel "Platform"@en .

## Groups (teams)
:PaymentsSquad a bs:Group ; skos:prefLabel "Payments Squad"@en .
:MerchantSquad a bs:Group ; skos:prefLabel "Merchant Squad"@en .
:PlatformTeam a bs:Group ; skos:prefLabel "Platform Team"@en .
:SRETeam a bs:Group ; skos:prefLabel "SRE Team"@en .

## Systems
:PaymentGateway a bs:System ; skos:prefLabel "Payment Gateway"@en .
:MerchantPortal a bs:System ; skos:prefLabel "Merchant Portal"@en .
:ObservabilityPlatform a bs:System ; skos:prefLabel "Observability Platform"@en .

## Components
:PaymentProcessor a bs:Component ; skos:prefLabel "payment-processor"@en ; bs:lifecycle "production" .
:FraudService a bs:Component ; skos:prefLabel "fraud-service"@en ; bs:lifecycle "production" .
:PayoutService a bs:Component ; skos:prefLabel "payout-service"@en ; bs:lifecycle "production" .
:MerchantOnboarding a bs:Component ; skos:prefLabel "merchant-onboarding"@en ; bs:lifecycle "production" .
:ReportingService a bs:Component ; skos:prefLabel "reporting-service"@en ; bs:lifecycle "experimental" .
:WebhookDispatcher a bs:Component ; skos:prefLabel "webhook-dispatcher"@en ; bs:lifecycle "production" .

## APIs
:PaymentsAPI a bs:API ; skos:prefLabel "Payments API (OpenAPI)"@en .
:MerchantAPI a bs:API ; skos:prefLabel "Merchant API (OpenAPI)"@en .
:PaymentEventsAPI a bs:API ; skos:prefLabel "Payment Events (AsyncAPI)"@en .
:FraudScoringAPI a bs:API ; skos:prefLabel "Fraud Scoring API (gRPC)"@en .

## Resources
:PaymentsDB a bs:Resource ; skos:prefLabel "payments-db (PostgreSQL)"@en .
:EventBus a bs:Resource ; skos:prefLabel "event-bus (Kafka)"@en .
:MerchantDB a bs:Resource ; skos:prefLabel "merchant-db (PostgreSQL)"@en .
:RedisCache a bs:Resource ; skos:prefLabel "redis-cache"@en .

Relationship Patterns

## Ownership
:PaymentProcessor bs:ownedBy :PaymentsSquad .
:FraudService bs:ownedBy :PaymentsSquad .
:PayoutService bs:ownedBy :PaymentsSquad .
:MerchantOnboarding bs:ownedBy :MerchantSquad .
:ReportingService bs:ownedBy :MerchantSquad .
:WebhookDispatcher bs:ownedBy :PlatformTeam .
:PaymentGateway bs:ownedBy :PaymentsSquad .
:MerchantPortal bs:ownedBy :MerchantSquad .

## System membership
:PaymentProcessor bs:partOfSystem :PaymentGateway .
:FraudService bs:partOfSystem :PaymentGateway .
:PayoutService bs:partOfSystem :PaymentGateway .
:WebhookDispatcher bs:partOfSystem :PaymentGateway .
:MerchantOnboarding bs:partOfSystem :MerchantPortal .
:ReportingService bs:partOfSystem :MerchantPortal .

## API provision
:PaymentProcessor bs:providesAPI :PaymentsAPI .
:PaymentProcessor bs:providesAPI :PaymentEventsAPI .
:FraudService bs:providesAPI :FraudScoringAPI .
:MerchantOnboarding bs:providesAPI :MerchantAPI .

## API consumption
:PayoutService bs:consumesAPI :PaymentsAPI .
:MerchantOnboarding bs:consumesAPI :PaymentsAPI .
:WebhookDispatcher bs:consumesAPI :PaymentEventsAPI .
:PaymentProcessor bs:consumesAPI :FraudScoringAPI .

## Resource usage
:PaymentProcessor bs:usesResource :PaymentsDB .
:PaymentProcessor bs:usesResource :EventBus .
:PaymentProcessor bs:usesResource :RedisCache .
:FraudService bs:usesResource :RedisCache .
:MerchantOnboarding bs:usesResource :MerchantDB .
:WebhookDispatcher bs:usesResource :EventBus .

## Domain membership
:PaymentGateway bs:belongsToDomain :PaymentsDomain .
:MerchantPortal bs:belongsToDomain :MerchantDomain .
:ObservabilityPlatform bs:belongsToDomain :PlatformDomain .

Service Catalog View

graph TD
    subgraph PaymentsDomain["Payments Domain"]
        subgraph PG["Payment Gateway (System)"]
            PP["payment-processor<br/>production"]
            FS["fraud-service<br/>production"]
            PS["payout-service<br/>production"]
            WD["webhook-dispatcher<br/>production"]
        end
    end

    subgraph MerchantDomain["Merchant Services Domain"]
        subgraph MP["Merchant Portal (System)"]
            MO["merchant-onboarding<br/>production"]
            RS["reporting-service<br/>experimental"]
        end
    end

    PP -->|"provides"| PAPI["Payments API"]
    PP -->|"provides"| PEAPI["Payment Events"]
    FS -->|"provides"| FSAPI["Fraud Scoring API"]
    MO -->|"provides"| MAPI["Merchant API"]

    PS -->|"consumes"| PAPI
    MO -->|"consumes"| PAPI
    WD -->|"consumes"| PEAPI
    PP -->|"consumes"| FSAPI

    PP -->|"uses"| PDB["payments-db"]
    PP -->|"uses"| EB["event-bus"]
    MO -->|"uses"| MDB["merchant-db"]

    style PaymentsDomain fill:#B3D9FF,stroke:#333,color:#000
    style MerchantDomain fill:#D4E6B5,stroke:#333,color:#000
    style PG fill:#E3F2FD,stroke:#333,color:#000
    style MP fill:#E8F5E9,stroke:#333,color:#000

Validation

.scripts/validate.sh --shacl payflow-model.ttl \
    core/core-shapes.ttl \
    modelingLanguages/backstage/backstage-shapes.ttl

Further Reading

• Modeling Languages Guide — how Backstage relates to ArchiMate, C4, and other languages
• Backstage as C4 Complement or Replacement — positioning guide
• Build Your Own Modeling Tool — how tools consume these assets
• Validation Guide — SHACL validation pipeline
• Backstage Documentation — official Backstage catalog docs
• Backstage System Model — entity types and relationships