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.
- Country A (birth country) is Taifafeki. Somsak is born at Kesaro
Provincial Hospital and gets his birth doses there (J1). On the GDHCN DEV
network, Taifafeki is played by the test participant XXR, whose DSC (kid
kW/6VnwPRKI=, hex916ffa567c0f44a2) is on the live DEV trust list. - Country B (country of residence, “home”) is Onesa. The family lives there (J2, J3, J4.0). On the DEV network it is played by a fictional participant, written XXU.
- J4.1 takes the family back to Taifafeki, a year later.
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:
provide-a-vhl-to-a-receiver(Holder) is J2, J3 and J4.1.receive-a-vhlis J2, J3 and J4.1 too. It names the Issuer as its actor, which looks wrong: OI-01.publish-,receive-,distribute-andretrieve-pki-materialare the trust anchor and the participants in J3.
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:
- 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).
- It prepares the CWT and the bytes to sign: STT-CWT-001…005, STT-ISS-004.
- 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.
- Pain point: The baby has no Taifafeki ID number, so his records would normally stay locked inside the Taifafeki hospital’s system.
- Enabler: A digitally signed QR card travels with the family — no ID number or database lookup needed.
- Policy: Babies born abroad can get a verifiable vaccine record before they have the host country’s civil registration or a national ID — and registering the birth at home still matters.
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.
- Pain point (J2a): Without a check, a forged or mistyped card could quietly become an official record.
- Pain point (J2b): Babies born abroad are invisible to the home health system until civil registration catches up — sometimes months later.
- Enabler (J2a): The phone reads the card offline, and keeps “what the family told us” clearly separate from “what we have verified”.
- Enabler (J2b): An offline form links the baby to his household immediately; it syncs once the phone finds a signal.
- Policy (J2a): Keep a clear line between what families report and what has been verified, and don’t grant trust too early.
- Policy (J2b): Newborns can be registered at home, offline, before civil registration or a national ID exists.
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.
- Pain point (J3a): Clinicians either distrust foreign paper and re-vaccinate, or trust it blindly.
- Pain point (J3b): Countries name and package vaccines differently, so doses get missed or repeated.
- Enabler (J3a): The signing key of Taifafeki is on the shared WHO trust list, so any clinic can check it locally.
- Enabler (J3b): The original code from Taifafeki is kept and the Onesa code is added alongside; the schedule engine calculates what’s due.
- Policy (J3a): Trust is decentralized: a clinic in Onesa verifies a signature from Taifafeki itself, without contacting Taifafeki.
- Policy (J3b): Never overwrite another country’s record: keep the original coding alongside the national one.
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:
- It assembles the IPS and Somsak’s DVCs.
- It encrypts them (STT-VHL-004, STT-VHL-007) behind a passcode-protected manifest with an expiry (STT-VHL-009).
- 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.
- Pain point (J4.0a): Many families share one smartphone; one-app-per-person designs leave them out.
- Pain point (J4.0b): Sending photos or PDFs of records leaks data and can’t be verified by the receiver.
- Enabler (J4.0a): A household wallet on one phone, with a separate health summary for each person.
- Enabler (J4.0b): A Verifiable Health Link: the QR holds only a locked pointer; the data stays home until the passcode is given.
- Policy (J4.0a): Design for shared devices (“One Family, One Phone”) so families with only one phone aren’t left out.
- Policy (J4.0b): Data sovereignty: the record stays in Onesa until the family authorizes someone to open it.
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:
- The viewer verifies the HCERT against Country B’s DSC in its copy of the trust list.
- It requests the manifest by ITI-YY5, signed with HTTP Message Signatures (STT-VHL-005, STT-VHL-006, STT-VHL-008).
- The Onesa gateway checks the passcode, the expiry and the consent, returns the manifest, and logs the access at home (
TrustDemoJ41Access). - The viewer decrypts the IPS and DVCs (STT-VHL-007) (
TrustDemoJ41Received). - 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.
- Pain point: Without the history, the doctor would repeat vaccines or have to guess.
- Enabler: The record is fetched live from Onesa, viewed without being copied, and an access log is sent home.
- Policy: Continuity of care across borders: each country keeps its own records, with no international patient registry and no vendor lock-in. What is agreed regionally is the data model and the trust list, not a shared copy of the data.
Questions for discussion
The journeys walkthrough closes with four policy questions:
- Identity for babies born abroad (J1, J2b): how should national immunization systems handle temporary ids for cross-border infants before civil registration is complete?
- Where trust begins (J2a, J3a): why should offline CHW devices store foreign cards as reported, not verified, rather than verify them in the field?
- 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?
- 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
- The workshop lives in the journeys viewer, beside the journeys it teaches from: the technical track (T1 to T7, with the two-day timetable of both tracks) and the policy-maker track (M1 to M7). Each module has a page there: its sessions, the journey steps it meets and its questions.
- The module × journey map shows where each workshop module (M1 to M7) meets each step above, and what is technical and what is policy at that point.
- The glossary defines the terms the policy-maker track uses, each linked to the Reference Architecture (DPI-H) and DTH-PHC glossaries. Its terms at each step are also shown on every step of the journeys viewer.
- The Country Canvas is the A3 table canvas (a cover and Sheets 1 to 6) the tables fill in.