STD-DEVEX-081: Service Catalogue Standards¶

Owner	Classification	Review Date	Status
CDO Office	Internal	April 2027	Active

STD-DEVEX-081: Service Catalogue Standards¶

Field	Value
Standard	STD-DEVEX-081
Title	Service Catalogue Standards
Status	Draft
Owner	Platform Team
Created	2026-04-03
Review	Quarterly

Purpose¶

Mandate that every Simpaisa service is registered in a central service catalogue with consistent metadata. When an incident occurs at 03:00, the on-call engineer must instantly know who owns the service, where the runbook is, and what the dependencies are. A service catalogue eliminates tribal knowledge as a single point of failure.

Scope¶

All services deployed to Simpaisa's Kubernetes clusters: payment services (Pay-In, Pay-Out, Remittance, Cards), platform services, KrakenD gateway, data pipelines, and supporting infrastructure services. Includes both externally-facing and internal services.

Catalogue Platform¶

Tool : Backstage (self-hosted on Kubernetes).
Data source : catalog-info.yaml files in each service repository (docs-as-code).
Sync : Backstage polls Bitbucket repositories every 15 minutes for catalogue file changes.
Access : All engineering staff have read access. Service owners have write access to their entries.

Required Metadata¶

Every service MUST register the following in its catalog-info.yaml:

Field	Description	Example
`name`	Service name (kebab-case)	`payin-service`
`description`	One-line description of purpose	`Processes inbound payment transactions`
`owner`	Owning team	`payments-team`
`tier`	Service criticality (1=critical, 2=important, 3=internal)	`1`
`dependencies`	List of upstream/downstream services	`[surrealdb, redis, nsq, channel-connector]`
`slo`	Link to SLO definition	`docs/slo.md`
`oncall`	On-call rotation identifier (PagerDuty)	`payments-oncall`
`repository`	Bitbucket repository URL	`bitbucket.org/simpaisa/payin-service`
`pipeline`	CI/CD pipeline URL	`bitbucket.org/simpaisa/payin-service/pipelines`
`api-docs`	Link to OpenAPI spec or API documentation	`docs/openapi.yaml`
`runbook`	Link to operational runbook	`docs/runbook.md`
`market`	Markets this service operates in	`[pk, bd, np, lk, iq]`
`product`	Business product	`payin`

Example catalog-info.yaml¶

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payin-service
  description: Processes inbound payment transactions across all markets
  annotations:
    backstage.io/techdocs-ref: dir:.
    pagerduty.com/service-id: P12345
  tags:
    - go
    - payment
    - tier-1
spec:
  type: service
  lifecycle: production
  owner: payments-team
  system: payments
  providesApis:
    - payin-api
  dependsOn:
    - resource:surrealdb
    - resource:redis
    - resource:nsq
    - component:channel-connector

Tier Definitions¶

Tier	Description	SLO Target	On-Call	Runbook Required
1	Critical path — transaction processing	99.95%	24/7	Yes
2	Important — portal, reporting, onboarding	99.9%	Business hours + escalation	Yes
3	Internal — tooling, dev utilities	99%	Best effort	Recommended

Update Requirements¶

Catalogue entry must be updated on every deployment that changes dependencies, ownership, or tier.
CI pipeline includes a catalog-lint step that validates catalog-info.yaml against the required schema.
Missing or invalid catalogue files block the deployment pipeline.

Stale Entry Detection¶

Monthly automated scan compares catalogue entries against live Kubernetes deployments.
Services in the catalogue but not deployed are flagged as potentially stale.
Services deployed but not in the catalogue are flagged as unregistered.
Stale entries report is sent to Platform Lead and owning teams for remediation.
Unregistered services must be catalogued within 14 days or decommissioned.

Dependency Visualisation¶

Backstage renders a service dependency graph from the dependsOn relationships.
Used during incident response to assess blast radius.
Used during architecture review to identify coupling and circular dependencies.

Actions¶

#	Action	Owner	Deadline
1	Deploy Backstage to Kubernetes	Platform Team	2026-Q2
2	Add `catalog-info.yaml` to all service repositories	Service Owners	2026-Q2
3	Integrate catalogue lint into CI pipelines	Platform Team	2026-Q2
4	Build stale entry detection automation	Platform Team	2026-Q3
5	Publish dependency graph dashboard	Platform Team	2026-Q3

References¶

MICROSERVICES-FRAMEWORK.md
STD-DEVEX-090-SERVICE-LEVEL-OBJECTIVES.md
STD-DEVEX-092-RUNBOOK-STANDARDS.md
INFRASTRUCTURE-STANDARDS.md