Skip to content
Registry stack docs v0 · draft
Search

Registry Atlas overview

Registry Atlas is a browser workbench for inspecting what a registry publishes before you write integration code. It fetches and parses the service catalogue, schemas, policies, forms, and evidence offerings a registry exposes at its metadata endpoints, shows you the discovered assets, and lets you inspect the service-first graph from public service to requirement, evidence option, provider, and access route.

Atlas does not run queries against live person-level data. It does not make authorization decisions. It is a discovery and review tool, not a data access gateway.

A typical workflow: you paste the registry’s metadata URL into Atlas, run discovery, browse the schemas and policies in the Registry tab, then open the Services tab to check which public services, requirements, evidence bundles, forms, providers, and data services the registry publishes. If a route is present, Atlas shows the endpoint URL and the relation evidence to take into your integration code.

Stack commitments: reviewability.

What Atlas is made of

Section titled “What Atlas is made of”

registry-atlas is a browser single-page application (SPA) built with React 19, TypeScript, and Vite. A companion Node.js/Express server runs alongside the SPA as a same-origin fetch proxy. The heavy analysis runs in your browser via WebAssembly; the Node/Express server is a same-origin fetch proxy for inspected URLs.

The SPA and proxy are separate processes. In development, pnpm dev starts both concurrently: the Vite dev server on port 5177 and the Express proxy on port 3717. See package.json for the full script list.

The inspection model

Section titled “The inspection model”

When you point Atlas at a registry metadata endpoint (a Data Catalog Vocabulary (DCAT) catalog URL), Atlas performs discovery in layers:

  1. The fetch proxy downloads the catalog document and each linked artifact it finds (Core Public Service Vocabulary Application Profile (CPSV-AP) service catalogues, distributions, SHACL shapes, JSON Schema files, ODRL policies, OGC API Records landing pages, OpenAPI descriptions, and form schemas).
  2. The Rust-compiled WASM core classifies each fetched artifact into a SemanticAsset kind: catalog, public_service, requirement, evidence_type, evidence_type_list, form, data_service, dataset, distribution, json_schema, shacl, policy, open_api, api_description, class, or metadata_index.
  3. The results are assembled into a DiscoveryReport, the portable evidence contract the service-first navigation and strict matching layers consume.

The UI presents the discovered material across four workspace tabs:

  • Overview: discovery summary, recognized profiles, validation status, and gaps.
  • Registry: searchable list of discovered datasets, services, distributions, and catalogs.
  • Services: service-first graph over CPSV-AP public services, Core Criterion and Core Evidence Vocabulary (CCCEV) requirements, grouped evidence options, providers, access services, forms, and gaps.
  • Evidence: raw DiscoveryReport JSON, artifact tree, and a comparison view that separates core-recognized metadata from publisher-specific metadata.

The comparison view offers three modes: core (only DCAT-standard recognized fields), publisher (registry-specific extensions), and diff (side-by-side).

The fetch proxy

Section titled “The fetch proxy”

The proxy runs at http://127.0.0.1:3717 and exposes a single endpoint:

GET /api/proxy?url=<target-url>

The proxy is not a general-purpose relay. It enforces a set of protective rules documented in server/index.mjs:

  • Only http:// and https:// scheme URLs are accepted. data:, file:, and ftp: URLs are rejected.
  • Private-network targets (RFC 1918 ranges, loopback, link-local, and IPv6 ULAs) are blocked in production mode unless ATLAS_PROXY_ALLOW_LOCAL=1 is set. This behavior is controlled by NODE_ENV and the ATLAS_PROXY_ALLOW_LOCAL environment variable.
  • Embedded credentials are stripped from the target URL before the upstream request is made.
  • The response content type must be in the allowed set: application/json, application/ld+json, application/schema+json, application/vnd.oai.openapi+json, application/yaml, text/*, and related types.
  • Response size is capped at 2 MB by default (configurable via ATLAS_PROXY_MAX_BYTES).
  • Redirects are followed up to three hops by default (configurable via ATLAS_PROXY_REDIRECT_LIMIT).
  • Upstream requests time out after 8 seconds by default (configurable via ATLAS_PROXY_TIMEOUT_MS).
  • DNS lookup is pinned before the HTTP request to prevent time-of-check/time-of-use race conditions.

Error responses use application/problem+json with machine-readable codes (invalid_url, dns_lookup_failed, private_network_blocked, upstream_timeout, response_too_large, content_type_blocked).

Bearer token handling

Section titled “Bearer token handling”

Atlas accepts an optional bearer token in the session URL entry field. Tokens you enter live in memory for the tab lifetime; they are not written to browser storage or to server logs. The token is forwarded as an Authorization: Bearer header in the proxy request and is discarded when the browser tab closes. You must re-enter the token in each new browser session.

Service-first discovery

Section titled “Service-first discovery”

The service-first view answers questions such as:

Which public service is published?
Which requirements does the service hold?
Which evidence option groups satisfy each requirement?
Which provider or access service can supply the evidence?
Which form is linked to the online channel?

Registry Atlas treats a Core Criterion and Core Evidence Vocabulary (CCCEV) EvidenceTypeList as one grouped evidence option. Every evidence type in the list is required together. Multiple lists on one requirement remain alternatives.

The UI labels missing authority, legal, form, provider, and access-route evidence as gaps. It does not convert those gaps into legal conclusions. The normalized report keeps generic assets and typed relations as the wire contract; typed views such as a public service view or requirement view are projections over that report.

The full normative contract for the service-first graph is in SERVICE_FIRST_DISCOVERY_SPEC.md.

The strict capability discovery engine

Section titled “The strict capability discovery engine”

Atlas also includes a strict capability discovery engine for exact-term checks. That engine answers questions such as:

Where can I find if someone is registered as a farmer?
What route would a properly authorized system use to access that answer?
What evidence supports the match, and what is still missing?

The engine is strict in v0.1. “Strict” means:

  • No fuzzy matching, synonym expansion, approximate semantic ranking, or hidden query rewriting.
  • No embeddings, language models, ontology reasoners, or large search infrastructure.
  • Every match is backed by machine-verifiable evidence: exact label match, exact IRI match, or an explicit reviewed mapping.
  • Documented canonicalization (whitespace trim, Unicode normalization, case fold for labels, compact IRI expansion) is applied before comparison. Stemming, edit distance, and semantic similarity are not applied.

You type the terms describing what you’re looking for; Atlas checks whether the registry’s published metadata contains them, and only matches exact terms (no fuzzy or AI inference).

The output is a set of candidate answer routes, not authority claims. A candidate route includes confidence, an access endpoint URL, evidence references, gaps (for example, LegalBasisUnknown, AuthorityUnknown, FreshnessUnknown), and review flags. Candidate routes point you to where data might be, with evidence for why. Authorization and legal access checks are outside Atlas’s scope.

The full normative contract for the capability discovery engine is in SYSTEM_CAPABILITY_DISCOVERY_SPEC.md.

Semantic asset discovery and fixtures

Section titled “Semantic asset discovery and fixtures”

Registry Atlas ships bundled fixtures for offline use and as validated test inputs. The key fixture files are:

You can export the raw report JSON from the Evidence tab and use it with the CLI for offline analysis. The full schema is in the Registry Atlas reference.

When to use Atlas vs. Relay or Notary

Section titled “When to use Atlas vs. Relay or Notary”

Use Atlas when you want to inspect what a registry publishes before you write integration code. For live queries against person-level data or runtime API calls, use Registry Relay or Registry Notary directly.

Relationship to Registry Lab

Section titled “Relationship to Registry Lab”

Registry Lab runs Registry Relay, Registry Notary, live Postgres and Zitadel services, the private OpenFn sidecar path, the static metadata publisher, and demo clients together in a single docker compose up. Atlas is not included in the Registry Lab compose topology at v0.1. To use Atlas with the Registry Lab demo, start Atlas separately with pnpm dev and point its URL field at http://127.0.0.1:4331/metadata/cpsv-ap.jsonld, or use the curated Registry Lab CPSV-AP service catalogue demo chip.

Status and v0.1 caveats

Section titled “Status and v0.1 caveats”

Registry Atlas is at v0.1. Several capabilities described in SYSTEM_CAPABILITY_DISCOVERY_SPEC.md are not yet supported:

  • The query assist layer (natural-language search, synonym suggestion, embedding-based ranking) is deferred to a later optional layer.
  • Reviewed mappings are defined in the spec but no ingestion interface or UI exists in v0.1.
  • The governance workflow for reviewed capability assertions is not yet implemented.
  • Refresh indicators showing when data was last fetched are not yet present in the UI.

Next

Section titled “Next”