Technical appendix

Technical view of the Twinome demo

Live demoApple passClinician scanNotifications
ProfileSourcesMedication listWhat changedWhat mattersNext stepWallet passClinician viewOutcomeAccess history
ProfileJ. SmithPasskey, trusted iPhone, web account
Medications53 items need review
Signals3Explained and evidence-linked
Pass versionv4Share active

only what was allowed

Shared health view

Example share request/api/passport/passport_jsmith_2026/resources?scopes=passport.summary.read,medications.read,pgx.summary.read,decisions.read,opportunities.read&purpose=treatment

Apps and care teams ask for specific information and a reason. Twinome only returns the parts the person allowed and the source data permits.

identitymedicationsallergiespgx-summarydecisionsopportunitiesactionsoutcomesprovenanceaccess-history
Open data view

each source has limits

Connected sources

Jordan self-reported contextuser / inbound-onlyno read / write assertions
Apple Health bridgedevice-health-hub / inbound-onlyno read / write assertions
Oura sleep and readinessdirect-consumer-api / inbound-onlyno read / write assertions
Consumer genomic uploaduser / inbound-onlyno read / write assertions
Mercy SMART-on-FHIR launchclinical-interoperability / bidirectionalread / write assertions
Northstar payer programcontracted-partner / bidirectionalread / write assertions

missing data is not proof

Source health

  • observableUser medication entryThe user may know facts no source contains, but unreported events remain unknown.
  • limited-windowNorthstar Patient Access APINo claim does not mean no medication use; it may mean cash payment, another payer, or no coverage.
  • observableConsumer genomic data uploadConsumer genomic data may not resolve every pharmacogene or clinical factor and may need confirmation before a medication decision.
  • limited-window23andMe raw data uploadMissing or unsupported loci must remain unresolved; Twinome never fills missing genotype as normal.
  • limited-windowApple Health / HealthKit mock connectorNo HealthKit sample may mean no data, denied data, limited history, device non-use, or sync failure.

minimum necessary package

Partner request demo

Mercy Urgent Careapproved / emergencyCovered by active patient-presented share and emergency profile.
Ouradenied / care-navigationOura is configured to contribute observations only and cannot read Passport data.
Clinician-led weight management partnerneeds-user-approval / partner-intakePartner intake requires explicit user action after an opportunity is explored.
TrialBridgeneeds-user-approval / trial-screeningTrial screening is separate research-like permission and cannot reuse treatment consent.

identity and medication basics

Your Twinome profile

Accountjordan.smith@example.test
SecurityPasskey + MFA + trusted device
Connections8 medication-relevant sources
Medication entryPGx uploadGenotype intakeExport/deleteCaregiver access

available when care happens

Apple Wallet pass

TwinomeMedication
Passport
HolderJ. SmithSince 2026
Active flags3Medications3Genes typed5
Pharmacogenomic phenotypes
CYP2C19Intermediate metabolizer
CYP2D6Poor metabolizer
SLCO1B1Normal function
VKORC1Increased sensitivity
DPYDNormal metabolizer

Reduced clopidogrel activation flag. Avoid treating old codeine entry as active until reconciled.

Scan for the clinician viewtwinome.health/p/8F2K-QX41 Updated 20:15 UTC
.pkpassNotify
Passport updates are readySend PGx review, medication list, access, clinician review, and outcome updates from the presenter console.

scan and review

Clinician snapshot

Scoped access blocked
  1. Active medications first: Sertraline, Clopidogrel, Metformin
  2. Severe allergy: Penicillin / Anaphylaxis
  3. PGx notes: CYP2C19 Intermediate metabolizer; CYP2D6 Poor metabolizer; SLCO1B1 Normal function
  4. Override capture: reason, practitioner, organization, outcome window
Open scan

permission plus source rules

Privacy controls

User permissionSource restrictionsContract permissionsJurisdictionRecipient entitlementPurpose

Blocked by source policy policy_src_payer_api.

treatment-usecare-navigation-useadvertising-prohibitedpayer-program-onlycontract-restrictedgenomic

what is active, old, or uncertain

Medication list with history

MedicationStateRx stateDoseEvidence qualityPGx
SertralineSSRI antidepressantactivetaken50 mg oral once dailyauthoritative-source-supportedCYP2D6, CYP2C19
ClopidogrelAntiplateletactivedispensed75 mg oral once dailyauthoritative-source-supportedCYP2C19
CodeineOpioid analgesicuncertainunknownunknown oral as needed, uncertainunknown-conflictingCYP2D6
SimvastatinStatinhistoricalstopped20 mg oral nightlyuser-reportedSLCO1B1
MetforminBiguanideactivetaken500 mg oral twice dailyuser-reportedNone

source to checked fact

How data comes in

AcquireStageValidateNormalizeReconcilePolicyProvenanceEvents
  • User medication entryuser-entry / user-reported
  • Northstar Patient Access APIpayer-api / authoritative-source-supported
  • Consumer genomic data uploadconsumer-genotype / user-reported
  • 23andMe raw data uploadconsumer-genotype / user-reported
  • Apple Health / HealthKit mock connectorhealthkit / partner-source-supported
  • Oura OAuth mock connectoroura / partner-source-supported
  • Mercy SMART/FHIR launch mockehr-fhir / authoritative-source-supported
  • Retail pharmacy fill feed mockpharmacy-feed / partner-source-supported

clinical and consumer stay separate

PGx handling

23andMe / Ancestry-style raw genomic uploadconsumer-genotype / user-reportedCYP2C19: resolved, CYP2D6: resolved, SLCO1B1: resolved, VKORC1: resolved, DPYD: resolved
23andMe v5 raw genotype uploadconsumer-genotype / user-reportedCYP2D6: requires-copy-number

medication-relevant state

What changed

  • recent-medication-startClopidogrel was dispensed within the last 30 days.
  • unresolved-pgxPossible codeine exposure intersects with a clinical CYP2D6 poor metabolizer phenotype.
  • cost-barrierUser reported missed metformin doses and cost friction.
  • user-goal-changedUser explicitly asked Twinome to help explore weight-management options.
  • recent-medication-startClopidogrel started or was dispensed recently.
  • unresolved-pgxCodeine has uncertain status and PGx relevance.

Medication signals

What Twinome noticed, with reasons

5 live rule outputs
highrule_cyp2c19_clopidogrel@1.0.0

Reduced clopidogrel activation risk

Your uploaded genomic data may be relevant to one current medication. Do not stop it yourself; ask a clinician whether confirmation is appropriate.

Confidence67%Clinician requiredYesOutcome window90 days
mediumrule_cyp2d6_codeine@1.0.0

Possible codeine mismatch

One old medication may not belong on your active list. Confirming it helps avoid confusion in urgent care.

Confidence69%Clinician requiredNoOutcome window30 days
mediumrule_cost_barrier_metformin@1.0.0

Access barrier may explain adherence

You reported missed doses and cost friction. Twinome can help you explore access support.

Confidence77%Clinician requiredNoOutcome window60 days

Helpful next steps

Suggestions that explain why they exist

8 opportunities / 4 active recommendations
  • decision / shownA current medication may need clinician reviewYou have a source-supported clopidogrel episode and a clinical CYP2C19 result in your Passport.
    high
  • opportunity / readyConfirm an old medicationYou entered codeine as an old medication and Twinome cannot verify active use from other sources.
    medium
  • opportunity / exploredPrescription cost help may be usefulThis is based on your explicit report of cost friction, not a commercial audience query.
    medium
  • opportunity / readyClinician-led weight-management care may be worth exploringYou explicitly asked for weight-management help; Twinome is not inferring a diagnosis from a medication.
    low
clinician-reviewsupported

Review clopidogrel with a clinician

A current antiplatelet medication intersects with a verified clinical CYP2C19 result.

Commercialnot-evaluatedBoundaryTwinome flags a review need; the clinician decides whether any therapy change is appropriate.
medication-reconciliationneeds-confirmation

Confirm whether codeine is still active

A historical medication entry is uncertain and would matter in an emergency medication review.

Commercialnot-evaluatedBoundaryThis is a reconciliation task, not a medication recommendation.
pgx-confirmationprovisional

Consumer genomic data confirmation may be useful for unresolved genes

The consumer genotype upload has a CYP2D6 copy-number gap while medication history contains possible opioid exposure.

Commercialnot-evaluatedBoundaryTwinome can route to clinical testing when a real medication decision depends on missing PGx.
prescription-savingssupported

Find a lower-cost way to fill metformin

Jordan reported missed doses and cost friction, so the problem is confirmed rather than inferred from claims.

Commercialeligible-after-exploreBoundaryThis is access support; Twinome does not interpret medication failure from refill data alone.

relevance before routing

Action Engine

RelevanceEligibilityMarketplaceAttribution
Confirm medication listCodeine is uncertain and intersects with a PGx flag.
eligible
Confirm PGx gapConsumer genomic data has a CYP2D6 callability gap, so Twinome does not treat the available upload as complete.
needs-review
Refill and access helpMissed doses and cost barrier were reported.
eligible
Compare prescription savingsThe user confirmed cost friction before Twinome considered a savings route.
eligible
Screen for a relevant trialPotential research screening is separated from treatment consent.
needs-review
Explore clinician-led careUser explicitly asked for weight-management options; routing waits for Explore.
needs-review

after Explore only

Fulfillment Router

Northstar covered pharmacy supporteligible / pmpmFind a lower-cost way to fill metformin
No partner selectednot-available / noneExplore clinician-led weight-management care

A route can exist only after an opportunity is relevant and the user chooses to explore.

technical boundary

Commercial Firewall

HealthKit HRVhealth-management onlyPayer claimspayer-program onlyGenomic signalno advertising, no profile sale

The router cannot query restricted derived signals for prohibited commercial targeting.

PayersEligibility, claims, pharmacy claims, cohorts, interventions, outcomes.
EmployersAggregate activation, engagement, savings, and privacy suppression.
ProvidersSMART-on-FHIR, clinician summary, override, write-back guardrails.
PGx labsVerified result import, provenance, white-label Passport activation.
TelehealthScoped intake, medication proposal, route disclosure, conversion.
Trial operatorsSeparate consent, pre-screening, disposition, outcome linkage.
Consumer genomic uploads23andMe and Ancestry-style uploads, marker coverage, and confirmation boundaries.
Partner APIOAuth, scopes, sandbox, webhooks, usage logs, SDK boundary.

run the company without spreadsheets

Internal Operations

User supportData qualityDuplicate identity reviewClinical safetyPrivacy requestsPartner configurationProgram administrationRevenue ledger
Ops shellEnterprise

decision to evidence

Outcomes Learning Loop

Decision -> Action -> Completion -> OutcomeAwaiting follow-up eventEvery outcome points back to DecisionObject version, rule version, context state, and provenance.

Monday walkthrough

Run the full platform loop

The runnable demo API returns the same loop shown here, including Medication Response Profile, compiled context, live clinical flags, DecisionObjects, action candidates, Wallet pass metadata, and audit events.

API
Loop readyProfile 3 active meds / 5 flags /5 runtime decisions / 8 opportunities /2 outcome links / 15 audit events

Audit and observability

Who accessed what, why, and when

15 events
  • ConsentGrantedCreated Twinome identity and granted core treatment consent.J. Smith / treatment / 2026-08-21 14:31:00 UTC
  • MedicationAddedAdded sertraline, metformin, and historical codeine entry.J. Smith / care-navigation / 2026-08-21 14:38:00 UTC
  • PGxResultAddedImported consumer genomic data and kept unresolved genes clearly marked for confirmation.Twinome ingestion / treatment / 2026-08-22 15:04:00 UTC
  • PassportConnectionCreatedConnected Oura as inbound-only; Oura can contribute observations but cannot read Passport data.Twinome Passport Connect / care-navigation / 2026-08-22 19:35:00 UTC
  • PartnerAssertionReceivedReceived medication dose observation and preserved HealthKit observability limitations.HealthKit mock connector / treatment / 2026-08-22 19:52:00 UTC
  • PassportAccessRequestedRequested scoped Passport resources from patient-presented QR share.Mercy Urgent Care / emergency / 2026-08-22 19:57:00 UTC
  • DecisionGeneratedGenerated three DecisionObjects with evidence, source quality, and outcome windows.Twinome rules engine / treatment / 2026-08-22 20:15:00 UTC
  • OpportunityGeneratedGenerated six OpportunityObjects after context and policy checks, before partner routing.Twinome opportunity engine / care-navigation / 2026-08-22 20:15:00 UTC
  • RecommendationShownShowed prescription-cost opportunity because the user explicitly reported cost friction.Twinome recommendation layer / care-navigation / 2026-08-22 20:04:00 UTC
  • PassGeneratedGenerated Apple Wallet-compatible Medication Passport package.Twinome Passport service / emergency / 2026-08-22 20:15:00 UTC
  • WalletDeviceRegisteredRegistered Wallet device library identifier for future pass updates.Apple Wallet / emergency / 2026-08-22 20:02:00 UTC
  • ClinicianSnapshotViewedPatient-presented scan opened limited clinician snapshot.Mercy Urgent Care / emergency / 2026-08-22 20:03:00 UTC
  • ActionExploredExplored refill and access help for metformin.J. Smith / care-navigation / 2026-08-22 20:05:00 UTC
  • FulfillmentRoutedRouted metformin savings after user explored the confirmed affordability opportunity.Twinome marketplace router / care-navigation / 2026-08-22 20:06:00 UTC
  • OutcomeObservedLinked action exploration back to DecisionObject decision_metformin_access.Twinome outcomes service / care-navigation / 2026-08-22 20:07:00 UTC