Adding a new dot

A new dot is a new network. You add it with configuration files in the Signals-DPG repo and a few settings in .env. This guide uses the Yellow Dot (education) network as the example. Its domains are student and tutor or counsellor, and its one action is connect.

Read Networks, domains and instances and The schema-driven model first. This page lists what to do; those pages explain the terms.

Before you start

• A local Signals-DPG setup that runs the default network. Follow SETUP.md in the Signals-DPG repo.
• The roles in the new network, who asks and who offers, and the fields each role fills in.

1. Create the network folder and network.json

1. Add a folder under examples/schemas/. Name it after the new network, in snake_case.
2. Add a network.json to it. Copy an existing network’s file and edit it.

examples/schemas/
  blue_dot/
  orange_dot/
  purple_dot/
  yellow_dot/
    network.json
    consent.json
    messages.properties

The top-level fields of network.json are:

Field	What it holds
id	The network id. Other files and settings refer to the network by this value.
display_name, description	The name and one-line description shown to people.
schema_standard	The JSON Schema draft the item schemas use.
domains	One entry per role (step 2).
instances	The running copies of the software that serve each domain. Each entry has instance_name, instance_url and domain_id. For local work, point instance_url at http://localhost:2742.
actions	What one domain can send another, for example connect. Each interaction names from_network, from_domain, to_network and to_domain. Leave it as {} for a listing-only network such as Orange.
dashboard_buckets	The labels used on dashboards for each status.

Use the same value for the folder name and the id. The UI picks colours by folder name and the API uses the id, so a mismatch leaves the UI on the default colours. The Yellow example folder does not follow this, so check its colours after you switch to it.

2. Add the domain schemas

1. Add one entry to domains for each role. For Yellow these are student and tutor or counsellor.
2. Give each domain an id, a description and an item_schemas block.
3. Key each item schema by its type and version, for example profile_1.0. The schema itself is JSON Schema.

Each domain entry also sets how it appears and when a profile goes live:

Field	What it does
contact_fields	Which schema fields hold the name, phone and email.
go_live_required	What must be complete before the profile can be found.
status_rules	How a profile moves between statuses such as new, active, at risk and inactive.
card, dashboard_tiles	What shows on cards and dashboards.
profile_completion_prompt	The heading and text that ask the person to finish their profile.

Mark fields that must stay private with "private": true, as Yellow does for phone number and email. Mark the field that holds the place with "location": "primary".

3. Set the network id and SERVED_DOMAINS

Point your instance at the new network. Change these lines in the root .env, then restart pnpm dev:api and pnpm dev:ui.

NETWORK_CONFIG_LOCAL_FILE="../../examples/schemas/yellow_dot/network.json"
SERVED_DOMAINS="<network-id>/student"
VITE_NETWORK_ID=<network-id>

• <network-id> is the network id set in its network.json. For Yellow it differs from the folder name.
• SERVED_DOMAINS lists <network-id>/<domain-id> pairs, separated by commas. Add the tutor or counsellor domain to serve both roles from one instance.
• The path must start with ../../, because the API resolves it from apps/api/.

Check that the API loaded the schemas:

curl -s http://localhost:2742/api/v1/network/schemas | head

4. Add the brand and UI theme

The colours, logo and sign-in text are separate from the network contract. A network works without them, but looks like the default network.

1. Colours. Add a brand.json beside network.json. Put colour overrides in a theme block. The UI reads brand.json files at build time and keys the colours by folder name.
2. Logos. Add PNG files to apps/ui/public/brand/<network-kebab>/, where the folder is the network name in kebab-case (yellow_dot becomes yellow-dot). logo.png and logo-light.png are required.
3. Sign-in text. The tagline and portal label come from an entry in apps/ui/src/theme/network-themes.ts, keyed by network id. Without one, the UI shows the Blue Dot text.

examples/schemas/yellow_dot/brand.json
apps/ui/public/brand/yellow-dot/
  logo.png
  logo-light.png

A brand is a skin for one deployment of an existing network. To add one, create examples/schemas/<network>/<brand-slug>/brand.json with only the fields that differ. The full field list is in apps/ui/public/brand/README.md in the Signals-DPG repo. See also Customisation & Branding.

5. Add the consent and messages files

1. consent.json. Add it beside network.json. It holds the terms, privacy and profile-creation documents, and one consent statement for each action and stage. Yellow has statements for connect at initiate and accept. Each document has a current_version and a list of versions. The API records the version people accept, so add a new version instead of editing an old one.
2. messages.properties. Add it beside network.json to change the email text for this network, for example the welcome email subject. List only the keys you want to change. The full key list is in apps/api/src/notifications/email/messages.default.properties.

Write __SUPPORT_EMAIL__ where the consent text needs a support address. The API replaces it with the value of CONSENT_SUPPORT_EMAIL.

A brand can override both files. Put the override in the brand’s sub-folder, for example examples/schemas/<network>/<brand-slug>/consent.json.

6. Add the voice prompts

If people will register or update their profile by phone call, add prompts for the new network to the AI-Agent-Prompts repo. Prompts are grouped by network at the top of the repo, then by agent.

1. Add one agent for each side, for example one for students and one for tutors or counsellors.
2. Follow the file layout on AI Voice Agent Prompts: conversation prompt per language, memory, and output.
3. Make the output fields match the domain schemas from step 2.

Check the new dot

1. Open the UI at http://localhost:5173 and sign in.
2. Check the colours, logo and sign-in text.
3. Create a profile in each domain and accept the consent.
4. Send a connect request from one domain to the other, and accept it.

Related

• Networks, domains and instances: the networks that exist today and their status.
• The schema-driven model: how schemas drive forms, cards and validation.
• Configuration: where other settings live.