Somsak is born in Taifafeki, grows up in Onesa, and one year later a doctor in Taifafeki can see every vaccine he has ever had, without a single record being copied across the border.

The story is the one the journeys walkthrough tells, moment by moment, with the people, the technical layer and the policy questions (interactive; its source is web/ in this repository), documented here as a WHO SMART Guidelines L2 DAK and L3 implementation guide. Its FHIR examples are materialized in this guide; the Journey examples page maps each moment and device screen to them.

XXR and XXU are DEV test participants, not either country’s production keys, and nothing here implies a real ministry. Every person is fictional.

The cast: Khamla SENGMANY (mother), Bounmy SENGMANY (father, holds the family phone), Vilay (community health worker, Village 04), Nurse Chanthason (Lomaru District Health Center) and Dr Anan (Taifafeki clinician, at the birth and a year later).

# Moment When Where Processes
1 Vaccinated and recorded birth day, 2025-10-28 Kesaro, Taifafeki J1
2 Found and registered 7 weeks old Village 04 (Khamla’s village), Onesa J2 (J2a read the cards, J2b register and refer)
3 A foreign record used for the next vaccine 10 weeks old District Health Center, Onesa J3 (J3a verify, J3b map and schedule)
4 Continuity across a border 12 months old Onesa to Taifafeki J4.0 (a wallet, b share link), J4.1

How far a clinician can rely on Somsak’s record, step by step (the journeys walkthrough’s “follow the record” ladder):

Step Record state Held where FHIR
J1 On paper: two signed DVCs Khamla’s bag HC1 QR (HCERT)
J2b Reported, not verified CHW phone, then sync Immunization.primarySource false
J3a Verified against the GDHCN trust list district clinic Provenance (verifier)
J3b Scheduled: counts toward the national schedule national records of Onesa schedule coding added, ImmunizationRecommendation, Task
J4.0 Portable: a summary the family can share records in Onesa, link on the phone IPS Bundle, Consent
J4.1 Shared and audited: viewed abroad, logged at home national records of Onesa Provenance, AuditEvent
  Process Where
J1 Issue the newborn’s birth-dose DVCs Country A
J2 Discover and refer an unregistered infant Country B
J3 Verify, import and schedule at the home clinic Country B
J4.0 Issue the family’s records to one phone as VHLs Country B
J4.1 Read a family member’s records at the point of care abroad abroad

Roles, actors and the guides’ actor definitions

Each lane is a role in scenarios/roles.json. Each actor in scenarios/actors/ names the role it plays. Its meta.definedBy gives the ActorDefinitions it is an instance of, and its meta.playsActor gives the smart-trust-tools actor. On the role, the guides’ names appear as otherNames (also known as).

Role (lane) Actor here WHO SMART Trust WHO smart-trust-phw IHE ITI VHL smart-trust-tools
caregiver Khamla SENGMANY (J1–J3), Bounmy SENGMANY (J4) Holder Holder VHLHolder vhl-holder
family-phone the Sengmany family’s shared phone (Bounmy’s) (Holder’s device) (Holder’s device: the personal health wallet) (VHLHolder’s device) vhl-holder
birth-clinic-system Kesaro Provincial Hospital, Taifafeki Issuer Issuer VHLSharer (HCERT side) vhl-sharer / hcert-issuing-system
issuer-key XXR’s DSC key (plays Taifafeki) Trust Network Participant (its PKI) Trust Network Participant — trust-network-participant / hcert-key-holder
chw-app CHW app, Onesa Receiver (triage read only) Receiver VHLReceiver vhl-receiver / hcert-verifying-system
home-clinic-ehr Lomaru District Health Center EHR Receiver Receiver VHLReceiver vhl-receiver / hcert-verifying-system
gdhcn-trust-anchor GDHCN DEV (WHO) Trust Network Anchor Trust Network Anchor TrustAnchor trust-anchor
national-portal Onesa national portal and gateway (XXU) Issuer; Trust Network Participant Issuer; Trust Network Participant VHLSharer vhl-sharer
poc-receiver Kesaro primary care clinic viewer Receiver Receiver VHLReceiver vhl-receiver
birth-clinic-vaccinator, community-health-worker, home-clinic-provider, poc-provider Dr Anan, Vilay, Nurse Chanthason, Dr Anan — (the people operating the systems; no ActorDefinition in either guide) — — —

smart-trust-phw’s requirements map onto the journeys as follows:

User scenarios

Each step names the requirements of smart-trust-tools it exercises, and the FHIR examples of this guide it produces. The stories are in scenarios/stories.json. Each moment ends with its pain point, what enables it, and the policy point it makes, as the journeys walkthrough presents them.

J1 — Vaccinated and recorded (Taifafeki, birth day)

Precondition: the issuer’s DSC is on the trust list. XXR’s document signer certificate (DSC), issued under XXR’s Country Signing CA (CSCA), was shared with the GDHCN, the Trust Anchor, before any DVC is signed; the GDHCN publishes it as a DID document. Sharing it is not a step of issuing. A DVC signed with a key whose DSC was never shared fails every receiver’s trust-list check (STT-VER-006).

Khamla, a woman from Onesa who works in Taifafeki, gives birth to Somsak on 2025-10-28 at Kesaro Provincial Hospital. He has no Taifafeki identity number. Dr Anan gives the Hep B and BCG birth doses and records them with their WHO PreQual product codes. For each dose, the hospital system does three things:

  1. It builds a DVCMinPreQual payload: STT-PAY-001…005 and STT-PAY-007, with subclaim −6 (STT-SEL-003). No identity document is needed (STT-PAY-005).
  2. It prepares the CWT and the bytes to sign: STT-CWT-001…005, STT-ISS-004.
  3. It has XXR’s key sign them (STT-COS-002, STT-COS-006), then finishes the HC1 text: STT-COS-001, STT-ZIP-001, STT-B45-001, STT-HC1-001, STT-QR-001.

Khamla leaves with two paper DVCs. In the demo: the library tests use the WHO guide’s own two signed HC1 strings (QR Code Generation §12), which verify against the live DEV trust list under the same XXR key. Somsak’s DVC payloads are illustrative. Live issuance in the app uses a TEST-ONLY key (STT-ISS-003), whose DSC is not on the GDHCN list, so its DVCs do not verify in J3.

J2 — Found and registered (Onesa, Somsak is 7 weeks old)

J2a. Khamla has brought Somsak home to Onesa. On a routine visit to Village 04, Khamla’s village, Vilay finds a newborn the Onesa system does not know exists. Her phone has had no signal for weeks. Khamla shows the two cards. The CHW app reads them with read-unverified (STT-VER-011; STT-B45-002, STT-ZIP-002, STT-CBR-003), which needs no trust list. It shows the doses, but checks no signature and saves nothing yet.

J2b. On the CHW app’s newborn form (structured data capture, TrustDemoHouseholdRegistration) she adds Somsak to the Sengmany household (TrustDemoHousehold), with a temporary id. Bounmy confirms the details as head of household. The app saves the doses read from the cards as reported by the family, not verified (TrustDemoJ2HepBReported, TrustDemoJ2BcgReported: primarySource false). Vilay refers Somsak to the district health center (TrustDemoJ2Referral). Everything stays queued on the phone, for 28 days if need be, and syncs when it next reaches a signal.

J3 — A foreign record used for the next vaccine (Lomaru District Health Center, Somsak is 10 weeks old)

Precondition: the DID documents are already loaded. Loading them is not a step of this visit. The clinic may be offline all day, so the EHR fetches nothing during it: its trust store holds the GDHCN DEV trust list as it was last refreshed, including XXR’s DSC DID document (STT-TRU-001, STT-TRU-002, STT-TRU-005). A clinic with no connection of its own refreshes it about weekly, when the CHW visits the base clinic or district health office, where Country B retrieves the list the GDHCN trust anchor distributes. A DSC published after that refresh is not in the clinic’s copy, so its DVC fails the trust-list check (STT-VER-006) until the next refresh.

J3a. Nurse Chanthason opens the referral and scans the QRs. The EHR verifies each DVC offline against that copy (STT-VER-001…009, STT-KID-002), without contacting Taifafeki. Both verify, so it imports them as FHIR Immunizations (TrustDemoJ3HepB, TrustDemoJ3Bcg) with provenance (TrustDemoJ3Verification; STT-VER-007, STT-VER-008), replacing the reported doses of J2. If a DVC fails (a tampered card, say), the EHR names the step and the reason, the doses stay unverified, and the nurse decides by national catch-up policy.

J3b. The Taifafeki Hep B product matches nothing on the national schedule. The EHR keeps the product coding of Taifafeki and adds the schedule coding beside it, from the national map (TrustDemoProductToOnesaEpi). For the Hep B product the map has no entry, so Nurse Chanthason makes the clinical call that it is the schedule’s birth dose (TrustDemoJ3Adjudication), and her decision is added to the map for the next clinic. The schedule (TrustDemoOnesaInfantSchedule) then runs: the birth doses count, and pentavalent 1, bOPV 1 and PCV 1, due at 6 weeks, are overdue at 10 weeks (TrustDemoJ3Recommendation), so Nurse Chanthason gives them that day. Khamla leaves with the date of the next doses (TrustDemoJ3Reminder). Over the year Somsak gets the rest of his doses and measles-rubella at 9 months, in Onesa.

J4.0 — Continuity across a border: one family, one phone (Onesa, 12 months later)

J4.0a. The family plans a trip to Taifafeki. Bounmy’s phone holds the family wallet, with a profile for each of them. Somsak’s summary (TrustDemoJ4Ips) shows six doses: two from Taifafeki, four from Onesa.

Precondition, as in J1: Country B’s DSC, under Country B’s CSCA, is already shared with the GDHCN, the Trust Anchor. That is what lets the clinic in Taifafeki verify the link in J4.1.

J4.0b. For Somsak, Bounmy shares his record with a 4-digit passcode he can say aloud, valid for 14 days. The portal records his consent (TrustDemoJ4Consent), then does three things:

  1. It assembles the IPS and Somsak’s DVCs.
  2. It encrypts them (STT-VHL-004, STT-VHL-007) behind a passcode-protected manifest with an expiry (STT-VHL-009).
  3. It issues the link as an HCERT, with the VHL at key 5 (STT-VHL-001, STT-VHL-002), signed with Country B’s DSC.

The QR holds only a pointer and a key: the record stays in Onesa.

J4.1 — Continuity across a border: a paediatrician in Taifafeki sees the full history (Kesaro, 12 months later)

Precondition, as in J3: the DID documents are already loaded. The clinic viewer’s trust store is a cached copy of the GDHCN trust list, including Country B’s DSC DID document (STT-TRU-001, STT-TRU-002, STT-TRU-005). The clinic refreshes it nightly or hourly, against about weekly at the offline J3 clinic. It does not need to be online to verify: verifying reads the cache and never fetches the list. A DSC published after the last refresh fails the trust-list check (STT-VER-006), naming that reason.

Back where it began, Dr Anan, a paediatrician, sees Somsak at a paediatric clinic in Kesaro. Bounmy shows the QR on his phone and says the passcode. The clinic viewer and the Onesa gateway take five steps:

  1. The viewer verifies the HCERT against Country B’s DSC in its copy of the trust list.
  2. It requests the manifest by ITI-YY5, signed with HTTP Message Signatures (STT-VHL-005, STT-VHL-006, STT-VHL-008).
  3. The Onesa gateway checks the passcode, the expiry and the consent, returns the manifest, and logs the access at home (TrustDemoJ41Access).
  4. The viewer decrypts the IPS and DVCs (STT-VHL-007) (TrustDemoJ41Received).
  5. It shows them to Dr Anan: every dose since the birth, viewed, never copied.

A wrong passcode is refused, and the attempt is still logged in Onesa (TrustDemoJ41WrongPasscode). If the HCERT does not verify (for example, Country B’s DSC is missing from the cached list), there is no digital verification. The clinic names the step and the reason (STT-VER-008), does not follow the VHL, and Dr Anan treats whatever the family can show as he would a paper record.

Questions for discussion

The journeys walkthrough closes with four policy questions:

  1. Identity for babies born abroad (J1, J2b): how should national immunization systems handle temporary ids for cross-border infants before civil registration is complete?
  2. Where trust begins (J2a, J3a): why should offline CHW devices store foreign cards as reported, not verified, rather than verify them in the field?
  3. Matching vaccines across countries (J3b): when a monovalent vaccine is given abroad but the home schedule uses a combination (pentavalent), how should schedule rules count the doses still due?
  4. Cross-border access and audit (J4.0b, J4.1): what agreements do countries need so that a clinician viewing a record abroad triggers an audit entry in the patient’s home country?

Modules, terms and the canvas

Edit this page on GitHub