Components
The console, the API, the browser runtime, the SDKs, PostgreSQL, Redis and the scheduled jobs, and how they connect.
PIEDAP Consent is one API service with a database, a session store and a static console. Client libraries run on your pages, in your apps and on your servers. Knowing the parts tells you what to protect and what can fail on its own.
The parts#
| Part | Where it runs | What it does |
|---|---|---|
| Console | Your team's browser | Static files served by nginx 1.27. Your team manages purposes, forms, regions, keys, records and requests here |
| API | The deployment | A Node.js 22 service. It serves the console API, the public SDK surface, the runtime files, the hosted pages, health and metrics |
| Browser runtime | Your visitors' browsers | JavaScript served by the API. It shows the notice, holds back tags and remembers the choice |
| Mobile SDKs | Your iOS and Android apps | Fetch the form for your own consent screen, record the answer and read the choices. They draw no banner |
| Server SDKs | Your servers | Node.js and Python packages that record consent, look people up and verify webhooks. The Node.js package also checks a receipt's signature |
| PostgreSQL 18 | The deployment | All configuration, records and evidence |
| Redis 7 | The deployment | Console sessions and the rate-limit counters shared between API replicas |
| Scheduled jobs | Inside the API process | Webhook delivery, expiry, daily anchors, retention and clean-up |
Two things sit outside the product. The PIEDAP IAM service signs your team in, because the console has no accounts of its own. A reverse proxy in front of the console ends TLS.
Two surfaces#
The API has two surfaces with separate credentials.
- The console API, under
/api, is used by your team. It takes an IAM session cookie, or an IAM API token sent as a bearer token. - The SDK surface, under
/sdk/v1, is called by your sites, apps and servers. It never uses cookies. It takes a publishable key or a secret key.
Health is at /health and metrics are at /metrics. The hosted pages, such as the privacy notice and the rights request form, are served from the SDK surface.
How the parts connect#
| From | To | How |
|---|---|---|
| A visitor's browser | API | Loads the runtime, asks for the form and sends the choice, with a publishable key |
| Your app | API | The same calls, with the app's id in the X-Piedap-App header |
| Your server | API | REST calls with a secret key as a bearer token |
| API | Your server | Webhooks, each signed with the endpoint's secret |
| Your team's browser | Console, then API | The console's nginx passes /api/, /sdk/ and /health to the API, so the browser sees one origin |
| API | PostgreSQL and Redis | Connections on a private network |
| IAM | Redis | IAM writes each session; the API reads it from the same Redis |
The API also makes outbound HTTPS calls. It calls your webhook endpoints, the sites you ask it to scan and the translation service, if you use one. It downloads the IAB vendor list from vendor-list.consensu.org. It calls IAM to check an API token.
Scheduled jobs#
Jobs run inside the API process, so there is no separate worker to deploy. Every replica schedules every job. A job that must not run twice takes a PostgreSQL advisory lock, so one replica does the work.
| Job | When |
|---|---|
| Webhook outbox | Every 15 seconds |
| Consent expiry, inactivity erasure, breach and usage reminders, scheduled scans, statistics | Hourly |
| Daily anchors | 00:15 UTC |
| Evidence retention | 03:00, only when the operator turned enforcement on |
| Clean-up of test records, webhook logs and held details | 04:00 and 05:00 |
| Rights request reminders | 08:00 |
Times other than the anchor's are in the time zone of the API process, which is UTC in the supplied image. Each run works from the state of the database, not from a calendar. A job that was due while the API was down catches up on its next run. Scheduled jobs lists every job.
What happens when a part fails#
Apart from short-lived caches and counters, the API keeps no state in memory except the queue of site scans. You can run several replicas behind a load balancer.
| Failure | Effect |
|---|---|
| PostgreSQL does not answer | /health returns 503. Nothing can be read or recorded |
| Redis does not answer | The SDK surface still works, with rate limits counted in each process. Nobody can sign in to the console |
| The API restarts | Webhooks wait in a database outbox and continue afterwards. A scan that was queued or running is marked failed |
| A webhook endpoint is down | The event is retried for about 21 hours. Consent writes are not delayed |
A browser's consent write is answered 429 |
The runtime applies the choice in the browser at once and sends the write again on a later page load |