# Protocols and their hierarchy

## The hierarchy

Everything you capture hangs from a **context** that Neurologyca assigns to your organization. Inside it, a **protocol** says what is measured and when: an ordered list of **positions**, each one running a **mechanic** (the script of one capture) made of **steps**.

**The catalogue** (Published by Neurologyca. Immutable once published.)

1. **Your organization**: Your organization in Engine. *↓ is assigned*
2. **Context** (`context`): A use case. It decides which protocols you can enrol people in. Not public: its **rules** may offer a mechanic as a microintervention after a capture. *↓ shares*
3. **Protocol group** (`protocol_group`): A family of protocols. It can be in several contexts. *↓ groups*
4. **Protocol** (`protocol`): What is measured, and how often. *↓ in order*
5. **Position** (`protocol_mechanic`): One slot of the protocol: its order and its schedule (when it can be captured). *↓ runs*
6. **Mechanic** (`mechanic`): The script of one capture. *↓ made of*
7. **Steps** (`step`): Each with its `step_type`, media and phases, plus the instructions.

**Your data** (Per person. You create it with the API.)

1. **User**: A person in your application. One per person: their **baseline**, shared by every protocol.
2. **Enrolment** (`userProtocolId`), belongs to a protocol: A person in a protocol.
3. **Capture of a position** (`userProtocolId` + `protocolMechanicId`), belongs to a position: What the person does in a position. Optional: once it completes, Engine may raise: **Interruption** (`interruptionId`) → microintervention capture.
4. **Results per step**, one per step: The indicators of each captured step.

| Level (API name) | What it is | What it decides |
| --- | --- | --- |
| `context` | A use case your organization has been given | Which protocols you can enrol people in, and whether captures can be interpreted |
| `protocol_group` | A family of protocols; it can belong to more than one context | What the interpretation focuses on |
| `protocol` | What is measured, and how often | Its positions, in order |
| `protocol_mechanic` (a **position**) | One slot of the protocol | When it can be captured: date, time of day and spacing |
| `mechanic` | The script of one capture | Its steps, fixed or free, and the screens shown between them |
| `step` (`step_type`) | One stimulus or task | Its type, suggested duration and what is shown |

The whitepaper calls the mechanic a *mechanism*; the API says `mechanic`. You see a protocol if any of the contexts of its group is assigned to your organization. A protocol made for a single organization is seen and enrolled only by that one: for any other, it does not exist (`404`).

## If no context fits

Your organization sees the contexts Neurologyca assigns to it, and the catalogue keeps growing. If none fits your case, you can commission one; to measure without a context, use [Measurement](/docs/guides/measurement/).

### Commission a context

If none fits, Neurologyca can build one for your case. Tell us what you want to understand, in which situation, and who the reading is for. Then:

1. We start from the published literature on the topic and from what the capture can actually measure.
2. We design the protocol and decide who the reading is for, and review it all with you.
3. We assign it to your organization, and you integrate it like any other.

Always within responsible use: the reading is meant to support the person and must never be used on its own to decide about them.

To commission one, write to Neurologyca support or talk to your Neurologyca contact.

### Context Maker (In development)

A tool we are developing to create a context from your case. You will describe your case in your own words and it will propose a context: what to measure, how to ask the person and who to write the reading for, starting from the published literature on the topic and from what the capture can measure.

If part of what you are after cannot be measured yet, it will tell you so and suggest what you can measure instead.

You will also be able to ask Neurologyca to go over the proposal with you. A proposal does not create a context by itself: Neurologyca assigns it, like any other.

## Catalogue and per person

| Neurologyca publishes it (catalogue) | Happens per person (execution) |
| --- | --- |
| Context, protocol group, protocol, position, mechanic, step, media, instruction | User, baseline, enrolment, the capture of a position, its results |
| The mechanics a context may offer as microinterventions (the rules that offer them are not public) | An interruption (an offer that happened, anchored to the capture that triggered it) and its microintervention capture |

You define nothing in the catalogue: you read it with `GET /catalog/*` and enrol people in it.

## A protocol at a glance

A synthetic example with three positions and one microintervention. Open a position to see its steps. Signed in with a team, you can switch it to one of your organization's protocols: DevLab reads it from your catalogue, without creating users.

| Position | When | Mechanic | Steps |
| --- | --- | --- | --- |
| 1 | Any time | Check-in | baseline_camera (free length), directed_question (free length), free_speech (optional) |
| 2 | ≥ 24 h after the previous capture | Check-in | baseline_camera (free length), directed_question (free length), free_speech (optional) |
| 3 | Day 7 ± 1 · 08:00–11:00 local | Check-in | baseline_camera (free length), directed_question (free length), free_speech (optional) |

| Microintervention | Steps |
| --- | --- |
| Breathing reset | reset_breathing (free length · 3 rounds) |

## Measurement, as Engine returns it

The Measurement protocol, from `GET /user-protocols/{userProtocolId}/schema`: one position, one step, any time.

| Position | When | Mechanic | Steps |
| --- | --- | --- | --- |
| 1 | Any time | Measurement | measurement_free (min 6 s · no max) |

## What you see in the API

| You want to know | Call |
| --- | --- |
| Your contexts and protocols | `GET /catalog/contexts`, `GET /catalog/protocols` |
| The positions of an enrolment and which one is next | `GET /user-protocols/{userProtocolId}` |
| The whole protocol, with schedules and scripts | `GET /user-protocols/{userProtocolId}/schema` |
| The script of one position | `GET /user-protocols/{userProtocolId}/mechanics/{protocolMechanicId}` |

```json
{
  "order": 1,
  "mechanic": {
    "name": "Measurement",
    "flowMode": "fixed",
    "steps": [
      {
        "order": 1,
        "type": "measurement_free",
        "minTimeSeconds": 6,
        "maxTimeSeconds": null,
        "optional": false
      }
    ]
  }
}
```

## Reading the catalogue

Your backend reads the catalogue with your key (the browser SDK never calls these routes). Each one returns only what is assigned to your organization, ordered by `id`.

| Route | Returns |
| --- | --- |
| `GET /catalog/contexts` | The contexts assigned to your organization: the themes that group your protocols |
| `GET /catalog/protocol_group` | The protocol groups of your contexts, plus the group of the baseline protocol, which everyone has. That group arrives with `interpreted: true` today, but you enrol nobody in it and it is not interpreted by itself (see [Baseline](/docs/concepts/baseline/)) |
| `GET /catalog/protocols` | The protocols you can enrol people in; `hasSchedule: true` means it can only start at its first position, and `interpreted: false` that `POST /analyze` answers `409 PROTOCOL_NOT_ANALYSED` (as with Measurement). Baseline is listed too, with `interpreted: true`, but you do not enrol people in it |
| `GET /catalog/protocol_mechanic` | The positions of each protocol (which mechanic, in which order) with their three clocks |
| `GET /catalog/mechanics` | The mechanics of your protocols and the microinterventions your contexts can offer, each with `constellationSubcontextId` (its analysis subcontext, or `null`) |
| `GET /catalog/mechanics/{pid}` | One mechanic with its full script, for a microintervention your own app decides to offer |
| `GET /catalog/mechanic_step` | Which step type, in which order, makes up each mechanic |
| `GET /catalog/step_types` | The step types, with `minTimeSeconds` and `maxTimeSeconds`: the two ends of each response window. Several can share a `type`: `current: true` marks the one in use |
| `GET /catalog/media` | The texts, images and videos of those step types |
| `GET /catalog/step_type_media` | Which media goes with each step type |

`@neurologyca/capture-server` reads six of them at once with `listProtocolLibrary()`.

## Positions and their clocks

A position can declare three independent clocks; it is available where they overlap:

- **Date**: a day counted from the first completed capture of the protocol (or a weekday), with a tolerance before and after. Once that window closes, the position is lost.
- **Time of day**: windows in the person's local time zone (the user's `timezone`; without one, a default of the environment).
- **Spacing** (`timeBetweenSessionsSeconds`): a minimum time since the previous capture. When clocks are enforced, Engine also keeps a minimum spacing between two captures of the same protocol, even when a position declares none; that minimum is a setting of the environment.

A protocol with `hasSchedule: true` declares a date or a time-of-day window for at least one position, and must be started at position 1. Spacing does not set `hasSchedule` and does not force the order. Engine declares these clocks and checks them when a capture is opened; whether a failed check rejects the capture or is only logged depends on the environment. [Sessions, enrolments and interruptions](/docs/concepts/sessions/) shows the answers.

## Steps, media and instructions

- `minTimeSeconds` and `maxTimeSeconds` are guidance for your interface: Engine does not enforce them, and they are often `null`.
- `presentationSeconds`, when present, says how long the step's question is meant to be shown; the visualizer prints it as «shown N s». It is guidance too: the SDK gives it to you (`PlanStep.presentationSeconds`) and does not apply it.
- `media[]` lists what can be shown in a step. When you show one, send its `pid` as `mediaId` with that step's batches.
- `instructions[]` are screens that are shown but not measured: `beforeStep` (with `step`) or `atEnd`.
- An `optional` step may be skipped. A cyclic step (`rounds`, `phases`) is still one capture.
- `targetConstellationHciId` names what the interpretation looks at in that step. The SDK gives it the same name, `PlanStep.targetConstellationHciId`.

## Microinterventions

A context may also define short mechanics that Engine can **offer after a completed capture**, such as a breathing exercise. They are not positions of your protocol: the offer arrives as an **interruption** of the capture that triggered it. See [Sessions, enrolments and interruptions](/docs/concepts/sessions/#interruptions-and-microinterventions).

## Versions

Published protocols never change: an edit creates a new version. An archived protocol can still be enrolled, with a `protocolNotice` that points to its replacement; a deprecated one accepts no new enrolments or captures.
