Architecture overview

The formal registry stack has four products: Registry Platform, Registry Manifest, Registry Relay, and Evidence Gateway. The stack is organized around two layers: a portable metadata layer and a runtime services layer. The metadata layer (Registry Manifest) compiles and renders discovery artifacts that describe what a registry exposes, without touching production sources. The runtime services layer enforces access against real data. Registry Relay compiles a governed registry contract into a fixed set of read-only operations over a read-only SQLite source. Evidence Gateway uses its own governed bundle and authoritative sources to answer bounded questions with signed assertions. Registry Platform provides shared Rust primitives consumed by both runtime services. Registry Mint is a supporting service rather than a fifth product: it issues the short-lived access tokens a resource server such as Evidence Gateway verifies, for deployments that have callers and no identity provider. Solmara Lab is a separate adopter project built around synthetic registry data. It is not a formal Registry Stack product or a production integration reference.

At runtime, Registry Stack exposes source data through two patterns:

• Protected registry APIs: controlled read-only interfaces over an existing registry source. Registry Relay implements this runtime surface.
• Minimum-disclosure assertions: one bounded question about one subject, answered with a signed assertion that carries the answer and not the record. Evidence Gateway implements this runtime surface.

The two patterns are independent. Evidence Gateway reaches its configured authoritative sources directly, over one of two coequal transports: a fixed HTTP JSON request to a fixed origin, which a production bundle must state as HTTPS, or one reviewed SQL statement against a read-only SQLite extract file mounted beside the process. It does not require Registry Relay or inherit Relay authorization. A deployment can configure a Relay-protected API as a fixed HTTP source, but Relay remains an ordinary source rather than part of the Evidence Gateway product boundary.

The separate Solmara Lab demo uses both transports. Among its Evidence cell definitions, the MoSD, NAgDI, and SIPF cells reach a Relay-protected API over a fixed HTTP JSON request, the NIA and SRO cells run a reviewed SQL statement against a published extract, and the CRA cell does both. A cell that reaches a Relay-protected API inherits no Relay authorization from it.

This split matters because it separates the obligation to describe (what a registry declares it can expose and under what policy) from the obligation to enforce (what a running service will actually return to an authorized caller). A reviewer can audit the portable metadata bundle before any runtime service is deployed. An integrator can validate schemas offline. A governance team can publish updated policy documents without touching deployment config.

Evidence Gateway and decision ownership

The following responsibility flow is normative for 1.0 project authoring:

1. A source system owns its operational data and any decisions made inside that source.
2. Registry Relay owns the compiled registry contract: which operations exist, which source columns become published properties, which access profile guards each operation, and which disclosure profile shapes each response. Relay returns only the properties a compiled disclosure profile declares. It does not assign a consumer consequence to those properties.
3. Evidence Gateway owns the bounded assertion plus the authorization and disclosure policy for evaluating and releasing it. The requirement is the unit of disclosure: purpose, audience, and requester entitlement decide whether a requirement may be invoked at all, and never narrow the answer it returns. Evidence Gateway does not turn the assertion into a consumer rule.
4. An assertion consumer determines how the returned assertion is used. The accountable decision owner retains responsibility for requirements, eligibility, qualification, prioritization, approval, routing, payment, workflow, and action policy.

These are three different policy categories: Relay contract and disclosure policy, Evidence Gateway authorization and disclosure policy, and consumer use, decision, and action policy. Project authors must keep them separate even when one deployment operates every component. The caller, assertion consumer, and decision owner can be the same component or separate components.

An assertion consumer can be a social-protection programme, admissions service, licensing authority, healthcare workflow, lender, insurer, or relying verifier. The caller is the technical client that invokes Evidence Gateway, which may be a portal, intermediary, or workflow connector acting for the consumer.

Context	Caller	Assertion consumer	Decision owner
Social protection	Case-management connector	Programme workflow	Administering authority
Public administration	Procedure portal or intermediary	Online procedure	Competent authority
Education	Admissions portal	Admissions workflow	Education institution
Healthcare	Clinical or case system	Care or public-health workflow	Provider or health authority
Regulated private service	Application platform	Lending or insurance workflow	Lender or insurer

An assertion may describe a property, classification, eligibility decision, status, or relationship. When the configured source returns the final fact, the requirement carries the source-derived acquisition posture and Evidence Gateway reports what the source decided rather than recomputing it. The requirement identifier and its review documentation must identify that fact as a source-owned decision.

Data and contract flow

1. Registry Platform provides reusable security and operational primitives consumed by runtime services.
2. A metadata manifest (registry-manifest/v1 schema) describes a registry through its catalog and defined collections. The Registry Manifest reference is authoritative for the current top-level keys and field schemas.
3. Registry Manifest compiles and validates the manifest, then renders a static discovery bundle (catalog, DCAT, BRegDCAT-AP, CPSV-AP, SHACL, JSON Schemas, OGC Records item collection, policies, evidence-offering metadata, embedded codelist metadata, and an index.json).
4. A separate authored registry contract (registry.yaml, kind: RegistryContract) declares the resources, operations, access profiles, and disclosure profiles one Registry Relay process will serve. relayctl compiles that contract against the observed source schema and seals the result, with every generated artifact (OpenAPI, JSON Schema, SHACL, and JSON-LD context and vocabulary), into one package. The governed registry publication page covers the compile-and-seal model; the relayctl reference covers the commands.
5. Registry Relay verifies that package at startup, opens its SQLite source read-only, and serves the fixed route set the package compiled. There is no adaptation step: the runtime executes only the statements the compiler produced, over the source columns the contract named, and returns only the properties a disclosure profile declares. The one runtime file (runtime.yaml, kind: RelayRuntime) binds local paths, the audit sink, secret references, limits, and an optional OIDC issuer, and cannot widen anything the package sealed.
6. Evidence Gateway evaluates one predefined, versioned requirement per request, aligned with CCCEV through its frozen field mapping. Rust owns authentication, authorization, the one fixed bounded source request, output validation, assertion construction, signing, and audit; a trusted Rhai script extracts the typed facts, and a second one prepares the request where the source declares one. An HTTP JSON source always declares a preparation script; a statement source usually declares none, because most of its parameters name the authorized selector field they come from and Rust binds those itself. Caller identity and authorization details can authorize or parameterize a request but cannot supply facts. That request reaches either a fixed origin configured directly for the authoritative system, which a production bundle must state as HTTPS and only a local unauthenticated one may state as numeric loopback, or a read-only SQLite extract file that the bundle names by logical profile and the runtime binds to an exact path.
7. Evidence Gateway returns the assertion as a flattened JWS JSON response (application/jose+json) by default. Where the immutable bundle and the one matched authority grant both permit it, the same stateless assertion may instead be serialized as a visibly unsigned JSON envelope or as an SD-JWT VC (application/dc+sd-jwt) under the frozen Version 1 profile. That serialization adds a response format, never a credential lifecycle: no issuance session, holder binding ceremony, status list, revocation, or presentation verification.
8. Where a deployment has callers and no identity provider, Registry Mint issues the short-lived access tokens Evidence Gateway verifies. The dependency runs one way: registry-mint carries registry-evidence as a development dependency so its tests drive Evidence Gateway’s authenticator, and registry-evidence depends on no other product crate.
9. A consumer receives the returned assertion. The decision owner applies any consumer-specific requirement, decision, workflow, or action rules outside Relay and Evidence Gateway. For what each project does and does not own, refer to the product overview pages linked in the capabilities table.

Capabilities at a glance

The two-layer design supports complementary capabilities: describe what a registry can provide, expose protected registry APIs, or answer a bounded question with a signed assertion that matches the purpose and policy of the request. Only Evidence Gateway signs. Relay responses carry no signature and no assertion. A caller cannot safely use a registry until its fields, schemas, services, policies, and evidence offerings are inspectable, so metadata comes first.

Capability	Use it when	Primary project
Describe registries	Other teams need to inspect fields, schemas, policies, services, and evidence offerings before integration.	Registry Manifest
Protected registry APIs	A SQLite extract or SQLite-backed registry needs a governed read-only API without replacing the source.	Registry Relay
Minimum-disclosure assertions	A caller needs one bounded fact about one subject, signed and audience-scoped, instead of access to the record behind it.	Evidence Gateway

Shared audit and operational behavior makes Registry Relay and Evidence Gateway reviewable: Registry Platform supplies the shared primitives for authentication, OIDC verification, HTTP security, audit envelopes, and cryptography that both runtime services compose, and the shared SD-JWT serialization crate that Evidence Gateway composes for its credential-format response.

Next

• Evidence Gateway quickstart maps what Evidence Gateway answers and the current authoring, operation, and verification material.
• Evidence Gateway security model states the invariants the runtime enforces and the duties that remain with the operator.
• Boundaries and map records what each product owns and does not own.