Architecture overview

The formal registry stack has six products: Registry Platform, Registry Manifest, Base Registry Engine, Registry Relay, Evidence Gateway, and Registry Discovery. Registry Platform is the shared primitive layer with no service of its own; the other five each ship a runtime or a tool an adopter deploys. 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. Base Registry Engine compiles a declared registry project into a PostgreSQL-backed writable registry: the schema, the REST API, the per-profile permissions, revision history, and an audit journal. 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 Discovery serves one immutable index, built offline from an operator-approved list of public provider descriptions, and leaves endpoint trust and native invocation to the relying application. Registry Platform provides shared Rust primitives consumed by every runtime product. 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 serves institutional data through three patterns:

• A writable system of record: a configuration-defined registry that holds the records itself, with create and update operations, per-profile permissions, revision history, and an audit journal. Base Registry Engine implements this runtime surface.
• 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.

Registry Discovery is not a fourth pattern. It publishes no institutional data: it answers where a provider is, from an index an operator built offline, and the relying application decides whether to trust that endpoint and invokes the product natively.

The three 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 Base Registry Engine, and it inherits the authorization of neither.

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 over a Base Registry Engine or Relay source

A deployment can configure a Relay-protected API as a fixed HTTP source, and an authenticated Base Registry Engine route the same way. Both are ordinary sources to Evidence Gateway: each is reached through the same bounded http-json source contract and an explicitly reviewed adapter, and neither becomes part of the Evidence Gateway product boundary.

That is the composed shape most institutions want. Base Registry Engine holds the records and owns every write to them. Evidence Gateway answers one bounded question about one of those records and releases the answer rather than the record: a licensing authority can hold licence records in Base Registry Engine and answer whether a licence is active without disclosing the licence. Nothing in the Evidence Gateway bundle knows that the origin behind it is Base Registry Engine. The bundle names an origin, one fixed request, and the fields a script may extract, and the same bundle would work against any source that answers that request.

The composition adds no privilege in either direction. A Base Registry Engine access profile governs what the configured Evidence Gateway client may read from the registry, and the Evidence Gateway bundle governs what any caller may learn from Evidence Gateway. A caller authorized against Evidence Gateway gains no Base Registry Engine access, and a caller authorized against Base Registry Engine gains no Evidence Gateway assertion.

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 business-registration portal, procurement service, licensing authority, environmental reporting service, 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
Business registration	Registration portal	Business verification service	Registration authority
Public administration	Procedure portal or intermediary	Online procedure	Competent authority
Education	Admissions portal	Admissions workflow	Education institution
Environmental permits	Permit portal	Facility compliance service	Environmental 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 registry project (registry.yaml, kind: RegistryProject) declares the entities, fields, relationships, vocabularies, access profiles, and events one Base Registry Engine deployment holds. bregctl compiles that project into the PostgreSQL schema, the REST routes, the per-profile permissions, revision history, and the audit journal, and packages the result. A signer approves the exact package bytes and an operator activates it; the breg runtime serves one activated package against one database, and its runtime file cannot widen what the package sealed. Base Registry Engine is the one product in the stack that holds records and accepts writes. The Base Registry Engine authoring reference covers the project file, and operate Base Registry Engine covers the package lifecycle.
5. 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.
6. 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.
7. 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.
8. 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.

Capabilities at a glance

The two-layer design supports complementary capabilities: describe what a registry can provide, hold and update records, expose protected registry APIs, answer a bounded question with a signed assertion that matches the purpose and policy of the request, or index where the providers of those surfaces are. Only Evidence Gateway signs. Base Registry Engine and 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
Hold and update records	The institution needs a system of record it does not hold yet, with create and update operations, revision history, and an audit journal.	Base Registry Engine
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
Index published providers	A relying application needs to find which providers publish a surface, without the index deciding whether to trust one.	Registry Discovery

Shared audit and operational behavior makes the runtime products reviewable: Registry Platform supplies the shared primitives for authentication, OIDC verification, HTTP security, audit envelopes, and cryptography that they 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.
• Base Registry Engine overview states what a registry project declares, what runs where, and which page an author, an operator, or an application developer opens first.
• Boundaries and map records what each product owns and does not own.