Adaptor Onboarding

This is the recommended path for a new adaptor — an organisation deploying Blue Dots for a district, state or domain. It assumes you have read Blue Dots as a DPG.

The path at a glance

1

Stand up Signals

Start with the network-aware backend — get the Signals API and UI running against local Postgres + Redis.

2

Define network + domains

Decide the network you participate in and the domains your instance serves, expressed as schemas and SERVED_DOMAINS config.

3

Add Aggregator

Add the Aggregator DPG to onboard partner organisations at scale, writing participant signals through the bulk-create paths.

4

Add capture channels

Web — the schema-driven Signals UI and the Aggregator portal — plus Voice AI for low-cost, local-language signal capture.

5

Integrate notifications

Wire SMTP (email) and an SMS provider for OTP, confirmations and match notifications.

6

Pilot & measure

Run a bounded pilot in one district and track the before/after metrics that matter.

Step 1 — Stand up Signals

Start with the network-aware backend. Follow Signals DPG Setup. At the end you should have the Signals API and UI running against local Postgres + Redis.

Step 2 — Define your network and domains

Decide the network you participate in (e.g. blue_dot) and the domains your instance serves (e.g. student, employer). Because the model is schema-driven, you express these as schemas and SERVED_DOMAINS config, not code. Define your item types (e.g. profile_1.0) up front.

Step 3 — Add the Aggregator DPG

When you are ready to onboard partner organisations at scale, add the Aggregator DPG. Configure it to write participant signals into your Signals instance through the bulk-create paths, authenticating with a Keycloak service token:

authorization: Bearer <client-credentials token>
x-acting-org-id: <the organisation you act as>

Register a confidential Keycloak client whose client id equals your organisation’s slug, then add it to KEYCLOAK_SERVICE_CLIENT_IDS on the Signals API — it is empty by default, so a new DPG is refused until listed. See Keycloak Setup.

Step 4 — Add capture channels

• Web — the schema-driven Signals UI and the Aggregator portal.
• Voice AI — for low-cost, local-language signal capture. A voice DPG integrates the same way an aggregator does (service-auth + bulk create). Ready-made prompt sets are published as DPGs — see AI Voice Agent Prompts.

On the assisted side, pick the intake method per campaign — offline camp, bulk upload, outbound campaign or inbound QR campaign. All four ship ready-made; see The Blue Dot Lifecycle.

Step 5 — Integrate notifications

Wire SMTP (email) and an SMS provider for OTP, confirmations and match notifications. Mailpit covers email locally.

Step 5b — Make it yours

Branding, operational settings, dashboards and a public landing page are configuration and presentation layers — none of them require touching Signals or Aggregator. See Customisation & Branding.

Step 6 — Pilot and measure

Run a bounded pilot in one district (as Ghaziabad and Dharwad did) and track the before/after metrics that matter: jobs surfaced, discovery time, cost per interaction, and conversion. See Pilots.

Onboarding checklist

• Signals API + UI running, migrations applied.
• Network schema and SERVED_DOMAINS defined; item types registered.
• Keycloak realm imported; admin user created.
• Aggregator DPG deployed.
• Service client registered (id = org slug), listed in KEYCLOAK_SERVICE_CLIENT_IDS, acting-org configured.
• SMTP + SMS providers connected.
• S3 bucket + credentials provisioned for bulk upload.
• Branding applied (brand.json, UI theme, Keycloak login theme).
• Route in (assisted / self) and intake method chosen per campaign.
• Pilot scope and impact metrics agreed.

Where to go next

• Activating Blue Dots in a District — the institutional path that runs alongside this one.
• Customisation & Branding — make the deployment your own.
• AWS Infrastructure Setup — take it to a cluster.