Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/preview/llms.txt
Full corpus: https://docs.registrystack.org/preview/llms-full.txt

# Architecture overview

> How the registry stack uses a two-layer design of portable metadata and runtime services to publish, consult, and prove registry facts.

The formal registry stack has four products: Registry Platform, Registry Manifest, Registry Relay,
and Registry Notary.
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 (Registry Relay, Registry Notary) binds those artifacts to real data, enforces
access control, evaluates claims, serves delegated evaluation between trusted Notaries, and issues
credentials.
Registry Platform provides shared Rust primitives consumed by both runtime services.
Solmara Lab is a separate adopter project that runs published stack images in local and hosted demo
topologies. It is not a formal Registry Stack product.

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

- Protected Registry APIs: controlled read-only interfaces over existing registry sources.
  Registry Relay implements this runtime surface.
- Evidence Gateway: the governed evidence path. A runtime service evaluates request context,
  source context, supported policy terms, freshness, redaction, and audit provenance before it
  returns a result or denial. Registry Notary implements claim evaluation and credential issuance.
  Registry Relay implements governed read routes when evidence is returned from a protected API.

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 and claim shapes offline. A governance team can publish
updated policy documents without touching deployment config.

{/* SVG diagram. Essential labels are restated in the HTML list that follows. */}
<figure>
  <img src="../../images/registry-architecture-flow.svg"
       alt="Architecture flow: Registry Platform provides shared primitives. Registry Manifest compiles
            metadata artifacts. Registry Relay binds those artifacts to protected runtime sources.
            Registry Notary evaluates Relay-backed or self-attested claims and issues credentials
            only from exact Relay-backed evaluation provenance.
            The separate Solmara Lab adopter project wires published runtime images into demo
            topologies." />
</figure>

## Evidence 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 source-specific acquisition, source-access policy, and typed normalization.
   Relay returns only the declared consultation outcome and typed outputs. It does not assign a
   consumer consequence to those outputs.
3. Registry Notary owns atomic, precise, reusable evidence statements plus the authorization and
   disclosure policy for evaluating and releasing them. Purpose-bound authorization controls who
   can request evidence and what can be disclosed. It does not turn the evidence statement into a
   consumer rule.
4. An evidence consumer determines how returned evidence 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 source-access and adaptation policy, Notary
evidence 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, evidence consumer, and decision owner can be the same component or separate components.

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

| Context | Caller | Evidence 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 |

Registry Notary can attest a decision already made by an authoritative source system. The claim
identifier and its review documentation must identify that fact as a source-owned decision.
Notary attests what the source decided; it does not recompute the decision or take ownership of
the source's policy.

## 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](../../products/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. Registry Relay starts with runtime config that binds the manifest's logical datasets and entities
   to actual data sources. Clients reach entity routes, metadata routes, and evidence-offering
   endpoints through configured auth.
5. Registry Relay executes compiler-pinned consultations. Its product-neutral `http`, `script`,
   and `snapshot` capabilities adapt reviewed source contracts and return only declared typed
   outputs. Registry Notary evaluates registry-backed evidence claims from those Relay outputs, or
   evaluates source-free and self-attested evidence claims without Relay. It renders evaluation
   results as
   `application/vnd.registry-notary.claim-result+json`
   or CCCEV-shaped JSON-LD (`application/ld+json; profile="cccev"`), and it materializes stored
   evaluations that pass issuance checks into SD-JWT VC credentials (`application/dc+sd-jwt`).
6. An evidence consumer receives the returned evidence. The decision owner applies any
   consumer-specific requirement, decision, workflow, or action rules outside Relay and Notary.
7. A trusted Registry Notary can call another trusted Registry Notary through
   `POST /federation/v1/evaluations` for signed delegated evaluation. Registry Manifest can publish
   discovery metadata for that relationship, but local Notary peer policy grants access.
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 one capability sequence: describe what the registry can provide,
expose protected registry APIs, then return evidence that matches the purpose and policy of the
request.
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](../../map/boundaries-and-map/) |
| Protected Registry APIs | A file, extract, database, or legacy registry needs a governed read-only API without replacing the source. | [Registry Relay](../../products/registry-relay/) |
| Evidence Gateway | A caller needs a status, predicate, selected value, redacted result, protected read, denial, or supported credential instead of unrestricted source-record access. | [Registry Notary](../../products/registry-notary/) and governed [Registry Relay](../../products/registry-relay/) routes |

Shared audit and operational behavior makes Registry Relay and Registry Notary reviewable:
Registry Platform supplies the shared primitives for authentication, HTTP security, audit envelopes,
cryptography, and credential support that both runtime services compose. The external
[Solmara Lab](https://github.com/registrystack/solmara-lab/tree/00cd51a2be4a405ef75d337ddcede0f9de134b1f)
adopter project gives reviewers runnable demo topologies without becoming part of the formal stack.

## Next

- [Evidence issuance](../evidence-issuance/) explains claim evaluation, disclosure policy,
  delegated evaluation, and credential issuance in Registry Notary.