Internal Developer Portal and Service Catalog — Operating Quantum Computers

A quantum platform becomes usable when developers can find the right capability without knowing every internal team, queue, vendor, and failure mode. An internal developer portal is the user-facing map of the platform.

Backstage describes its software catalog as a centralized system for ownership and metadata across software and related ecosystem entities [R208]. Quantum platforms need an equivalent catalog, but the catalog must include QPUs, simulators, runtime contracts, benchmark suites, approved workload patterns, data products, and evidence templates.

Diagram loads as you read

Internal Developer Portal and Service Catalog · Figure 1

View diagram source

flowchart TB
    Portal[Developer portal] --> Catalog[Service catalog]
    Portal --> Docs[Technical docs]
    Portal --> Templates[Experiment templates]
    Portal --> Status[Platform status]
    Portal --> Evidence[Evidence viewer]
    Portal --> Support[Support routes]

Catalog entities

Diagram loads as you read

Catalog entities · Figure 2

View diagram source

classDiagram
    class QPU {
      qpu_id
      modality
      provider
      baseline_policy
      access_tier
    }
    class Simulator {
      simulator_id
      method
      max_qubits
      noise_support
    }
    class RuntimeContract {
      primitive
      shot_policy
      mitigation_profile
      admission_policy
    }
    class WorkloadPattern {
      pattern_id
      allowed_backends
      validation_suite
    }
    class EvidencePackage {
      package_id
      schema_version
      retention_policy
    }
    QPU --> RuntimeContract
    RuntimeContract --> WorkloadPattern
    WorkloadPattern --> EvidencePackage
    Simulator --> WorkloadPattern

The portal should model capabilities, not just URLs. Users should be able to answer: “Can I run this workload? On what target? Under what constraints? What evidence will be produced?”

Service tiers

Diagram loads as you read

Service tiers · Figure 3

View diagram source

flowchart LR
    Tier[Quantum service tier] --> Sandbox[Sandbox]
    Tier --> Research[Governed research]
    Tier --> Production[Claim-bearing production]
    Tier --> Restricted[Restricted or regulated]
    Sandbox --> Cheap[low cost, low assurance]
    Research --> Review[reviewed experiments]
    Production --> Evidence[evidence package required]
    Restricted --> Controls[enhanced controls]

A user should not need to infer service tier from a backend name. The service tier should be explicit and connected to admission control.

Developer journey

Diagram loads as you read

Developer journey · Figure 4

View diagram source

journey
    title Quantum developer journey
    section Discover
      Find workload pattern: 4: Developer
      Compare targets: 4: Developer
    section Prepare
      Generate template: 5: Developer
      Run simulator checks: 4: Developer
    section Submit
      Pass admission checks: 3: Platform
      Track job status: 4: Developer
    section Review
      Inspect evidence package: 4: Reviewer
      Promote or revise claim: 3: Reviewer

The portal should reduce support tickets by making the safe path the obvious path.

Golden paths

A golden path is a pre-approved route from problem type to artifact.

Diagram loads as you read

Golden paths · Figure 5

View diagram source

flowchart LR
    Problem[Problem type] --> Pattern[Approved pattern]
    Pattern --> Template[Repo template]
    Template --> Checks[CI checks]
    Checks --> Runtime[Runtime contract]
    Runtime --> Evidence[Evidence package]
    Evidence --> Review[Review checklist]

For example, a “small VQE chemistry experiment” golden path may provide a repo template, simulator gate, resource estimate, runtime contract, cost envelope, evidence schema, and review checklist.

Ownership metadata

Every catalog entry needs an accountable owner.

Illustrative listing · yaml

apiVersion: quantum.platform/v1
kind: RuntimeContract
metadata:
  name: sampler-prod-small
  owner: team-quantum-platform
  support: slack://quantum-platform-help
spec:
  primitive: sampler
  service_tier: governed-research
  max_shots: 200000
  allowed_workload_patterns:
    - qaoa-small
    - benchmark-clifford
  evidence_schema: qevidence.v7

Diagram loads as you read

Ownership metadata · Figure 6

View diagram source

flowchart TB
    Entity[Catalog entity] --> Owner[Owner]
    Entity --> Support[Support route]
    Entity --> SLA[SLA or SLO]
    Entity --> Policy[Admission policy]
    Entity --> Docs[Docs]
    Entity --> Templates[Templates]

Ownership is not a label. It is who gets paged, who approves changes, and who retires broken capabilities.

Portal anti-patterns

Diagram loads as you read

Portal anti-patterns · Figure 7

View diagram source

flowchart TB
    Anti[Portal anti-patterns] --> LinkFarm[Link farm]
    Anti --> Stale[Stale backend descriptions]
    Anti --> NoOwner[No owner metadata]
    Anti --> HiddenPolicy[Admission rules hidden]
    Anti --> NoEvidence[Evidence not discoverable]

A portal that only aggregates links becomes another place to search. A portal that encodes ownership, policy, examples, and evidence becomes operational infrastructure.

Practical rule

A developer portal should not make quantum easy by hiding constraints. It should make constraints explicit enough that users choose safe, supported paths by default.