# Design

This section covers the technical architecture and internal design of OpenG2P Registry. It describes the foundational data structures, processing pipelines, and cross-cutting concerns that underpin the platform. Each topic provides insight into how the registry is built, how data flows through the system, and the design decisions that shape its behaviour.

## Architecture overview

OpenG2P Registry is built as a set of FastAPI-based microservices that communicate through well-defined internal APIs and asynchronous task queues. The principal technology components are:

* **FastAPI** -- serves the REST API layer for both staff-portal and partner-facing endpoints.
* **Celery workers** -- handle all asynchronous processing including ingestion, outgestion, deduplication, and computation tasks.
* **PostgreSQL** -- primary data store with column-level encryption for sensitive fields.
* **Redis** -- used for caching, session management, and as the Celery message broker.
* **MinIO** -- object storage for documents, attachments, and raw ingestion payloads.
* **Keycloak** -- identity and access management for staff users, partner systems, and registrant authentication.

The functional architecture diagram is available on the [Registry landing page](/products/registry/registry.md).

## Key design principles

| Principle                   | Description                                                                                                                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Metadata-driven**         | The core platform is domain-agnostic. Register structure, sections, tabs, and UI forms are all driven by metadata configuration rather than hard-coded logic.                                                  |
| **Change-request-centric**  | Every mutation to registry data flows through an approval workflow. No record is created or modified without a corresponding change request.                                                                   |
| **Asynchronous processing** | Celery workers handle ingestion, outgestion, deduplication, and computation. This decouples the API layer from heavy processing and enables horizontal scale-out.                                              |
| **Schema-driven UI**        | JSON schemas stored in register metadata drive the rendering of forms in the staff portal, eliminating the need for per-register frontend code.                                                                |
| **Envelope encryption**     | Sensitive columns are encrypted at rest using AES with a Data Encryption Key (DEK) that is itself protected by an asymmetric KMS key. Read and write operations never call the KMS, avoiding latency overhead. |

## Design topics

The following sub-pages cover individual design topics in detail:

{% content-ref url="/pages/XCZeaF8EGyPHjuLa2at6" %}
[Data Model](/products/registry/registry/design/data-model.md)
{% endcontent-ref %}

{% content-ref url="/pages/1Fz8gaNQR7s9XMvWJgYR" %}
[Change Management](/products/registry/registry/design/change-management.md)
{% endcontent-ref %}

{% content-ref url="/pages/UMr7quSOgpZbXrLFFD13" %}
[Ingestion Pipeline](/products/registry/registry/design/ingestion-pipeline.md)
{% endcontent-ref %}

{% content-ref url="/pages/SfsQOtHFbteKMi3f6DgY" %}
[Outgestion Pipeline](/products/registry/registry/design/outgestion-pipeline.md)
{% endcontent-ref %}

{% content-ref url="/pages/wzgV4knedeLDNTPgKoPb" %}
[High level design](/platform/platform-services/consent-management/design/consent-management.md)
{% endcontent-ref %}

{% content-ref url="/pages/MZ7IBKCSQeJSuMZTkWZJ" %}
[Encryption at Rest](/products/registry/registry/design/encryption-at-rest.md)
{% endcontent-ref %}

{% content-ref url="/pages/9XE7QwgRwFUG3hji3VFG" %}
[Partner APIs](/products/registry/registry/design/partner-apis.md)
{% endcontent-ref %}

{% content-ref url="/pages/LuL1N7FHxe5EVDvILuD1" %}
[Deduplication](/products/registry/registry/design/deduplication.md)
{% endcontent-ref %}

{% content-ref url="/pages/nOAbiWS0autyWLUUyxO4" %}
[Broken mention](broken://pages/nOAbiWS0autyWLUUyxO4)
{% endcontent-ref %}

{% content-ref url="/pages/Jixogggcxb45IurTwyYv" %}
[VC Issuance](/products/registry/registry/design/vc-issuance.md)
{% endcontent-ref %}

{% content-ref url="/pages/rrh4zlTx6wyJBIfFpWv5" %}
[Registrant Auth - OIDC](/products/registry/registry/design/registrant-authentication-oidc-widget.md)
{% endcontent-ref %}

{% content-ref url="/pages/QzggEsflHFsGAiZanw44" %}
[UI Engineering](/products/registry/registry/design/ui-engineering-design.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openg2p.org/products/registry/registry/design.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.