High-Level Architecture

The Blue Dots stack is organised into clear horizontal layers, with two parallel verticals — Aggregator and Signals — that share datastores and integrations.

The layered view

The Blue Dots layered architecture: Apps (Aggregator App, Signals App); Auth — a single Keycloak spanning both verticals (OIDC, shared realm and service tokens); API (Aggregator API BFF, Signals API network-aware); shared datastores (Redis, PostgreSQL, Object Storage) and integrations (SMTP, SMS). DBs and integrations are shared across both verticals.

Layer by layer

Apps. Two web front-ends. The Aggregator App is the organisation-facing portal for onboarding and bulk upload. The Signals App is the schema-driven UI that renders forms and cards directly from network and item schemas.

Auth. Both verticals authenticate against one shared Keycloak realm (named per network via KEYCLOAK_REALM). People sign in with the OIDC authorization-code flow on a Keycloak-hosted login screen; integrating DPGs use client-credentials service tokens. Because the realm is shared, the API checks a token’s audience and realm role rather than trusting its signature alone. See Identity & Auth.

API. The Aggregator API is a Fastify backend-for-frontend that owns the aggregator database and the registration/approval/bulk-upload flows. The Signals API is the network-aware Fastify backend that owns items, actions, events and cross-instance discovery.

Datastores. Shared across both verticals:

PostgreSQL — system of record (Drizzle ORM; item tables are partitioned in Signals).
Redis — sessions, caches and the background-job queue.
Object Storage (S3) — bulk-upload files and assets. S3 is a real cloud dependency, not part of the local Docker stack.

Integrations. SMTP for email (Mailpit locally) and SMS for notifications and OTP delivery.

Ingress & platform (cloud). In a cloud deployment, a shared common-services layer fronts both verticals with a Kong ingress controller and provisions cert-manager (TLS) and the shared Postgres + Redis. How this is provisioned and deployed is covered in Infrastructure & Deployment Architecture.

Two verticals, one network

The Aggregator vertical is an on-ramp: it feeds participant signals into the Signals vertical, which is the network. In the MVP the Aggregator writes to Signals only through controlled bulk-create paths and otherwise reads from it.

One Keycloak (OIDC) authenticates both verticals: the Aggregator vertical (Aggregator App → Aggregator API) bulk-creates into and reads from the Signals vertical (Signals App → Signals API → Network discovery). Both share PostgreSQL, Redis and Object Storage (S3). Both verticals share one Keycloak realm.

Dive deeper into each vertical in Signals DPG and Aggregator DPG.