Registry & Relay

Both modules operate on organisational master data (not per-citizen data), so they carry no RLS — protection is applied at the HTTP layer by permission.

Ring System · R1 — the service registry

The registry answers a management question: how complete is the inventory of public services, how digital is it, and how close is it to once-only? Every service passport conforms to the CPSV-AP vocabulary.

Passport status

Status	Meaning
draft	Not visible in the public catalogue
published	Exposed through /api/v1/catalog/*
archived	Retired

Proactivity levels

Following the Estonian model — from information only to automatic service:

Level	Meaning
information	Information is published, nothing more
online	Applications are accepted online
once_only	Data the state already holds is not asked for again
proactive	Offered without the citizen applying at all

The overview counts services per level and computes the average statutory processing time.

Evidence and once-only

registry_evidences is the evidence catalogue. Each record carries an in_khur flag: does the state data exchange already hold this information?

The passport ↔ evidence link carries a from_citizen flag: is this document demanded from the citizen, or does the agency fetch it from a system itself?

Once-only violation

Every case where in_khur = true and from_citizen = true is a once-only violation — the citizen is asked for something the state already has. GET /api/v1/registry/once-only lists them and, using the annual frequency, estimates the burden this places on citizens.

Versions and delta

Every publish creates a passport version (registry_service_versions). The Delta* fields hold the difference against the pre-reengineering baseline — a negative value is an improvement (fewer steps, less time).

Endpoints

registry.view reads, registry.manage writes. admin satisfies both.

Method	Path	Permission
GET	/api/v1/registry/overview	view
GET	/api/v1/registry/catalog	view
GET	/api/v1/registry/once-only	view
GET	/api/v1/registry/services · /{id}	view
GET	/api/v1/registry/services/{id}/versions	view
GET	/api/v1/registry/services/{id}/once-only	view
GET	/api/v1/registry/evidences · /life-events	view
POST PUT DELETE	/api/v1/registry/services…	manage
POST	/api/v1/registry/services/{id}/publish · /archive	manage
PUT	/api/v1/registry/services/{id}/evidences	manage
POST PUT DELETE	/api/v1/registry/evidences…	manage
POST DELETE	/api/v1/registry/life-events…	manage

UI: Admin → Registry (/admin/registry, /admin/registry/services, /admin/registry/evidences).

Relay — cross-platform request routing

Relay accepts time-bound requests from an upstream platform, dispatches them to downstream platforms, tracks the SLA, and collects the responses.

flowchart LR
    U[Upstream platform] -->|POST /relay/requests| R[(Relay)]
    R -->|assignment| D1[Downstream A]
    R -->|assignment| D2[Downstream B]
    D1 -->|respond| R
    D2 -->|respond| R
    R -->|forward-up webhook| U

Statuses

Request: received → dispatched → in_progress → fulfilled (or overdue, rejected).

Assignment: pending → acknowledged → in_progress → done (or overdue, rejected).

SLA tracking

Mechanism	Behaviour
Reminders	Nudges are sent downstream at 75% and 90% of the SLA window
Escalation	Once an assignment is overdue, a grace period later it escalates to the supervisor automatically
Timeline	received · dispatched · reminded · escalated · responded · fulfilled · overdue · breach_notified · forwarded_up

Escalation grace

In the core module RelayEscalateGrace is 2 minutes — a template default. Production deployments lengthen it to match their real SLA.

Endpoints

Method	Path	Permission
POST	/api/v1/relay/webhook	— (peer platform call)
POST	/api/v1/relay/requests	manage
POST	/api/v1/relay/assignments/{id}/respond	manage
POST	/api/v1/relay/requests/{id}/forward	manage
GET	/api/v1/relay/overview · /requests · /requests/{id}	view
GET POST DELETE	/api/v1/relay/platforms…	view / manage
GET POST DELETE	/api/v1/relay/routes…	view / manage

A RelayRoute is a service_code → platform routing rule with its own SLA per target.

UI: Admin → Relay (/admin/relay, /admin/relay/config, /admin/relay/{id}).

How ingest/respond is protected

In this reference implementation the requests and assignments writes are guarded by JWT + relay.manage. In production the correct shape is for upstream/downstream platforms to call them through the gateway (m2m OAuth).