Episode Lineage

A single patient journey (from an intake through appointments, tasks, and eventually a care plan) produces many resources across many types. What keeps them coherent is one join key: the EpisodeOfCare. Every resource in a journey references the same episode, so you can assemble the whole arc from any starting point in one hop.

One episode per journey

When a patient first engages with an assessment, the platform opens (or re-attaches to) a persistent EpisodeOfCare for that patient and entry. The episode spans the relationship: it holds the intake, the assigned condition, and any resulting protocols over time. It also records which assessment opened the journey, so the originating scope is always reachable.

You do not create episodes yourself. POST /v1/assessments opens one server-side, idempotently, and returns the episode reference in its response, so re-starting the same assessment re-attaches to the existing episode rather than duplicating it.

Everything points at the episode

Each spine resource references the episode through its natural FHIR field:

• Appointment.supportingInformation
• Task.basedOn
• CarePlan.supportingInfo

Because the link is consistent, the episode is the single anchor you query against to build a coherent patient view. You do not have to walk a chain of references between resources; you fan out from the episode.

Why lineage matters

If you are building a patient view (a timeline, a "what's next" panel, a journey summary), the episode is what makes it correct and complete. Without a shared key you would have to guess which appointment relates to which intake and which task belongs to which plan. With the episode, membership is explicit: a resource is part of the journey if and only if it references the episode.

This also gives you a clean boundary. A patient may have several journeys at once (a skin concern and a thyroid assessment). Each has its own episode, so scoping to one episode gives you exactly one journey's resources.

Reading resources by episode

Find the episode, then fan out. Every search runs on the record plane and is scoped to the signed-in patient, so you never filter by patient yourself. If you just called POST /v1/assessments, use the episode reference from its response; otherwise look it up:

import type { EpisodeOfCare, Appointment, Task, CarePlan } from '@palamond/sdk/fhir';

const episodes: EpisodeOfCare[] = await palamond.searchResources('EpisodeOfCare', {
  status: 'active',
});

const episodeRef = `EpisodeOfCare/${episodes[0].id}`;

const [appointments, tasks, carePlans] = await Promise.all([
  palamond.searchResources('Appointment', { 'supporting-info': episodeRef, _sort: 'date' }),
  palamond.searchResources('Task', { 'based-on': episodeRef, _sort: '-_lastUpdated' }),
  palamond.searchResources('CarePlan', { 'supporting-info': episodeRef }),
]);

That is a complete journey view: its scheduled visits, its open and completed tasks, and its care plan, all keyed off one episode.

Next

• Clinical Spine - The gates the journey passes through.
• Appointments and Encounters and Tasks - The resources hung off the episode.