Persona graph views do not answer the persona's question: problem statement, requirements, and a path to one view per role

[ma3u]

The problem: one graph, four people, no answer

/graph renders the same force-directed hairball for every role. A gold "purpose" node sits in the middle, nodes are placed on rings by their Neo4j label, and everything the persona subgraph contains is drawn at equal weight. The page answers "what is in the database around you", never the question the person opened it with. Below, per persona: what they need to see, what the view shows today, and why that fails.

1. Patient (Maria Schmidt, ?persona=patient)

What a patient needs in one view: the handful of parameters that put them at risk for preventable disease (blood pressure, LDL, HbA1c, BMI, and the diagnoses behind them), what they should do next (the SPE recommendations and study findings, with a priority), and who is using their data under which consent, with a way to withdraw.

What the view shows: 85 nodes and 166 links. A ring of thirty diagnoses drawn at the same size whether they are "Acute viral pharyngitis" or "Diabetes mellitus type 2". Twenty other patients by name (the fixture lists Anisha16 Grayce293, Brett333 Waylon572 and so on) and fifteen OMOP research subjects, none of which are hers. Edge labels like FROM_DATASET repeated eight times on top of each other, MAPPED_TO, GRANTS_ACCESS_TO. The legend explains layers ("Research Anonymization", "Medical Codes"), not her situation.

Why it fails: there is no state and no severity. Nothing says which value is out of range, which recommendation is high priority, which consent is active. The risk scores that the profile API already returns (diabetes 0.65 high, cardiovascular 0.42 moderate) do not appear at all. Showing other patients' names in a patient's own view is, on top of that, the wrong thing to show under Art. 3 and Art. 8, even with synthetic data.

2. Researcher (Research Analyst, ?persona=researcher)

What a researcher needs in one view: their current researches with their state (permit valid until, application pending since, request answered or not, transfer done), the datasets they are allowed to use today, and the other datasets and studies near their own that they are missing, with a reason why they are relevant.

What the view shows: 46 nodes and 44 links, almost all of them OMOP concept mappings: "Hypertension (OMOP)" coded as 314529007, "Medication review" coded as 160904001, "T2D (OMOP)" mapped to a SNOMED concept, dataset dependencies DEPENDS_ON and CONFORMS_TO. The permit, the pending application, the open statistical request, the expired purpose credential and the two completed transfers that exist for this persona in the fixtures are not in the picture. Other studies do not exist as a concept in the view.

Why it fails: the graph is organised by data model layer (clinical, analytics, standard codes) when the researcher's question is organised by state (allowed, pending, blocked, missing). Relevance to their own study is never computed, so "what else is out there" cannot be shown.

3. Health data access body (?persona=hdab)

What the body needs in one view: the operations that are non-compliant right now: a transfer without a contract, a contract signed before the permit, an access attempt without a permit, a user whose credential expired, a permit about to lapse; and, turned on itself, its own decisions past their statutory deadline.

What the view shows: 34 nodes and 51 links: thirteen verifiable credentials, nine participants, three contracts, three approvals, three applications, one policy, all drawn the same way. ISSUED_TO and HOLDS_CREDENTIAL thirteen times each.

Why it fails: an authority view without state is a directory. Nothing is red. The compliance matrix, permit register and audit log that the platform already serves contain, as of the fixture date, thirteen findings (two overdue decisions, one transfer without contract, one refused applicant still attempting access, one credential expired with accesses logged after it, two quality labels expired, one permit expiring). None of them reaches the graph.

4. Hospital / data holder (?persona=hospital)

What the holder needs in one view: which data consumers are trusted (credentials presented, permit issued, contract signed, access log consistent) and which are not, which contracts are missing for data that is already flowing, and whether the holder's own duties are in order: dataset descriptions (Art. 77), the quality label (Art. 78), the access log (Art. 73(1)(e)).

What the view shows: 59 nodes and 91 links: nine datasets, twelve eEHRxF profiles, five distributions, thirteen credentials, nine participants, contracts and approvals. A well-formed catalogue picture.

Why it fails: trust is a derived property, not a label, and the view derives nothing. A consumer with no credential in the wallet, a consumer with an expired purpose credential, and a consumer whose permit was refused but who is still attempting transfers all look identical to the one that is fully in order. The holder's own expired quality label is a node like any other.

What the four have in common

• Structure instead of state. Nodes carry a label and a layer, never a status, a severity, a deadline or an "as of" time.
• The persona changes the filter, not the question. The ring layout, colours and legend are the same for everyone; only the set of labels differs.
• Nothing is derived. Trust, overdue, expired, chain broken, relevant: every one of these is a small query over data the platform already has, and none of them is computed.
• No way in and no way out. Nothing tells the person where to start, and a click on a node does not lead to the page that owns the record.
• Labels speak Neo4j. OMOPConditionOccurrence, FROM_DATASET, MAPPED_TO are shown to a patient.

What the platform already has, and what is missing

The mock fixtures under ui/public/mock/ mirror the live API shapes, so this is what a persona view could be built from today.

Persona	Available now	Missing for the one view
Patient	patient_profile (risk scores with factors, 8 conditions, 4 medications), patient_insights (2 recommendations with priority, 2 findings with evidence level), patient_research (3 programmes, 2 consents with trust centre DID)	Measured values with LOINC codes and the lab's reference range (Klarbefund already produces them as FHIR Observations, #186), a per-patient access log (Art. 8), a per-study opt-out state (Art. 71)
Researcher	permits (7 entries with decision due dates), requests (Art. 69), analytics (permit and cohort counts), admin_audit (negotiations, transfers, access log), credentials, catalog (21 entries with consumers), patient_research (other studies)	A study registry beyond the three patient-facing programmes, variable-level dataset descriptions (Art. 77) for real relevance, the researcher's own SPE session state
Access body	compliance matrix (application, approval, contract per consumer), permits, requests, admin_audit, credentials	Timestamps on the chain (contract signed relative to permit), enforcement records (Art. 63), the Art. 59 activity report linked to the operations behind it
Data holder	catalog, compliance, credentials (quality label with conformance, completeness, timeliness), admin_audit filtered by provider DID	A quality label per dataset (one per holder today), a description completeness score (Art. 77), the holder's Art. 60 duty checklist

Two fixture defects to fix on the way: several ehdsArticle fields still carry proposal numbers (Art. 46, 50, 51, see docs/ehds-article-numbering.md), and expired credentials keep status: "active", so anything that trusts the flag is wrong.

What Regulation (EU) 2025/327 requires per persona (adopted numbering)

Persona	Articles the view rests on	What the view therefore has to show
Patient	Art. 3 access to own data, Art. 8 information on who accessed it, Art. 14 priority categories (patient summary, lab results, discharge reports, imaging), Art. 10 opt-out from primary use, Art. 71 opt-out from secondary use, Art. 58 access bodies inform the public of results	Priority-category data first, the access log, the opt-out state, results from studies that used the data
Researcher	Art. 53 permitted purposes, Art. 54 prohibited purposes, Art. 61 duties of users, Art. 66 minimisation, Art. 67 application, Art. 68 permit (decision within 3 months of a complete application), Art. 69 statistical request, Art. 72 trusted holder, Art. 73 secure processing environment, Art. 75 HealthData@EU	Permit state and dates, what the credential allows, where the data sits, what is prohibited, other sources and studies
Access body	Art. 55 designation, Art. 57 tasks (publish applications and decisions, 57(1)(j)), Art. 58 obligations towards natural persons, Art. 59 reporting, Art. 63 enforcement (revoke, fine, exclude up to five years), Art. 68 timeline, Art. 78 quality labels	Broken chains, overdue own decisions, enforcement history, cross-border flows, the annual report as a by-product
Data holder	Art. 60 duties (make data available under a permit, describe datasets, keep logs), Art. 61 what users may do, Art. 73(1)(e) access log, Art. 77 dataset description, Art. 78 quality and utility label	Trust per consumer, permit and contract coverage, own description and label state

Trust, in EHDS terms, is a chain, not a flag: DCP credentials (membership, participant, purpose), an Art. 68 permit, a DSP contract, and an access log that agrees with all three. A persona view has to compute it that way.

Questions to decide here

1. Do we replace /graph per persona with a state-first view, or add it as /overview and keep the explorer for drill-down?
2. Which persona goes first? The access body view has the most findings per pixel; the patient view is the webinar story (HL7 AI Challenge Winners Showcase webinar, 14 October 2026: deck, uptime, blog article #252).
3. Should derived state (trust, overdue, expired, chain broken) move into the API and Neo4j (a ComplianceFinding node type), so it is queryable and auditable rather than computed in the browser?
4. Article numbering: renumber the fixtures to the adopted text now, or only on touch as docs/ehds-article-numbering.md says?
5. Accessibility (ADR-010): a severity list is the accessible path; is a 3D canvas acceptable as an enhancement only?

Proposed approaches, a framework comparison and four working prototypes are in the comments below.

Related: #252 (webinar), #186 (Klarbefund lab values), #19 (NLQ for researchers), #13 (GraphRAG), ADR-010 (WCAG), ADR-019.

[ma3u]

Approaches

1. One question per view, layered stack. The persona's question defines three to four layers in the persona's words; the graph is filtered and re-labelled to answer it; state (red pulsing: act now or a violation, amber: pending or expiring, green: in order, blue: information) and flows (particles on links where data actually moves) are the visual grammar. A severity list beside the canvas carries the same signals as text, each citing its article. Best fit for the four roles above. Risk: layers are hand-designed per persona, so a new role costs a design, not a filter.
2. Radial "constellation" dashboard, 2D, with drill-down into the graph. Centre = the person or organisation, rings = severity, a click opens the current explorer scoped to the node. Cheapest, no WebGL, accessible by construction. Loses the "everything in one space" feel.
3. Keep the force graph, add persona lenses (today's approach, improved). Dim and re-rank by persona, add halos and state to nodes. Least work, but it still shows structure instead of state, and the hairball stays.

Recommendation: 1 as the hero view per persona, with 2's severity list as the left panel, and today's explorer kept as the "open in graph" drill-down from any node.

Whichever wins, the derived state is the real work: 80 percent of a persona view is deciding what is overdue, expired, untrusted or relevant. That logic belongs in the API (/api/graph?persona= already exists) so that the web and the iOS app share it.

[ma3u]

Frameworks for a modern, animated, 3D view

Library	Rendering	3D	React	Licence	Fit
3d-force-graph / react-force-graph-3d (vasturiano)	three.js WebGL	yes	wrapper exists	MIT	Fixed-z layers, custom node objects, link particles and camera tweens out of the box. The 2D sibling is what /graph uses today, so the mental model carries over. Used in the prototypes.
react-three-fiber + drei	three.js, declarative	yes	native	MIT	For the production version: layers, halos and flows as React components, animation with react-spring or GSAP, full control. More code than 3d-force-graph, more freedom.
Reagraph	WebGL (three)	yes	native	Apache 2.0	Opinionated graph component with 3D layouts, clustering, lasso. Less control over custom scene objects.
Sigma.js 3 + graphology	WebGL 2D	no	community wrapper	MIT	Fast, accessible 2D; the right choice if approach 2 wins.
AntV G6 5	Canvas / WebGL	3D extension	wrapper	MIT	Rich layouts and plugins, 3D is secondary.
Cosmograph / cosmos.gl	GPU compute	no	native	cosmos.gl MIT; Cosmograph component: check licence	For 100k+ nodes, which no persona view needs.
deck.gl	WebGL / WebGPU	yes	native	MIT	Geospatial strength (a HealthData@EU cross-border map), heavier for a small graph.
Neo4j NVL	WebGL	no	wrapper	proprietary	Native to the database, no 3D.
yFiles, KeyLines / ReGraph	Canvas / WebGL	partial	yes	commercial	Best layouts on the market, at a cost.

Animation and transitions: the graph library's own camera tween for focus, GSAP or react-spring for panel and layer transitions, and prefers-reduced-motion respected (auto-orbit and pulsing off).

Platform constraints on ehds.mabu.red that any choice has to live with: the nonce CSP in middleware.ts (static prototypes need the poc/ exclusion, a React page gets the nonce for free), X-Frame-Options: DENY (no iframes, draw in-page), and Cross-Origin-Embedder-Policy: credentialless (CDN scripts load, CDN fonts need CORP headers).

[ma3u]

Four prototypes, live

Index: https://ehds.mabu.red/poc/persona-3d/ (also on GitHub Pages under /poc/persona-3d/). Source: ui/public/poc/persona-3d/, one shared engine (engine.js) and one page per persona, no build step, pinned CDN import of 3d-force-graph 1.80 (three.js r183). Data: the fixtures listed in the problem statement, pinned to 2026-09-23. Merged in #266.

Each view is a short stack of labelled layer discs in the persona's words. The force layout runs only in the plane, so the layers stay readable. Red halos pulse for "act now" or a violation, amber for pending or expiring, green for in order, blue for information. Particles move along a link when data actually flows. The left panel lists the same signals as text, sorted by severity, each citing the article of Regulation (EU) 2025/327 it rests on; a click flies the camera to the node; the selected panel deep-links to the live page that owns the record.

Patient https://ehds.mabu.red/poc/persona-3d/patient.html
Layers: prevention (what to do next), my risks and the parameters behind them, my record, who uses my data under which consent. Reads the risk scores from patient_profile, links each risk factor down to the diagnosis that drives it, hangs the SPE recommendations and findings above, and shows the consents flowing to the studies and their trust centres. It names its own gap: no measured values in the fixture.

Researcher (PharmaCo Research AG) https://ehds.mabu.red/poc/persona-3d/researcher.html
Layers: my studies and studies near them, my permits, requests, contracts and credentials, datasets I use or publish, relevant datasets I do not use yet. Relevance is a word overlap between the study's declared data needs and the catalogue entries, so lab results, problem lists and medication requests surface as candidates. The purpose credential that expired in June is red.

Health data access body (MedReg DE) https://ehds.mabu.red/poc/persona-3d/hdab.html
Layers: participants, the application to permit to contract chain, regulated datasets, operations. Every matrix row of /api/compliance becomes a chain and every gap a red or amber node: the thirteen findings named in the problem statement, from two overdue own decisions to a refused applicant still attempting reads.

Hospital / data holder (AlphaKlinik Berlin) https://ehds.mabu.red/poc/persona-3d/hospital.html
Layers: consumers and how far we trust them, permits and contracts covering our data, our datasets, credentials and quality labels. Trust is derived: membership credential plus participant credential plus purpose credential plus permit plus contract. Two consumers have no credential in the wallet, one is out of permit, one is refused and still knocking, and the holder's own quality label expired five days before the fixture date.

What building them taught us

• The persona view is mostly a query, not a rendering. Each page spends most of its code deriving state; that belongs in the API, shared with the iOS app.
• The compliance matrix, permit register and audit log disagree in small ways (a contract without an application decision, a permit with no contract but a running transfer). Real data will disagree more; that is what the access body view is for.
• A fixed "as of" date is needed for demos; the prototypes pin 2026-09-23.
• Background tabs never tick a layout whose cooldown is wall-clock based; the engine uses warmup and cooldown ticks instead.
• A 3D canvas is not an accessible path. The severity list is, and it has to stay the primary one (ADR-010).

[ma3u]

Update: a parameter opens into its time series

In the patient prototype every parameter node (HbA1c, fasting glucose, LDL, total cholesterol, systolic and diastolic pressure, BMI, eGFR) now carries its measurements over time.

• Click a parameter and the single measurements unfold as chained nodes on the record layer, one per date, coloured by whether they sit inside the printed reference range. A second click folds them again.
• The right panel shows the latest value, the trend against the printed range ("rising from 6.4 over 23 months"), a chart with the reference band, a plain-language description of the analyte (taken from the Klarbefund analyte dictionary), the series as a table, and the FHIR facts.
• The severity list gains one line per parameter that is out of range or moving the wrong way, so "HbA1c rising from 6.4 to 7.6 %, outside the printed range" sits directly under the diabetes risk it explains.

Data: a fictional FHIR R4 Observation bundle for patient P1 (ui/public/poc/persona-3d/data/observations-p1.json, 8 LOINC-coded parameters, 6 dates, the lab's own reference range on every resource), in the shape the Klarbefund app exports. Per ADR-039 the range is shown as printed, never app-generated; the trend words compare first and last value against the printed range width and are not a clinical judgement.

Live: https://ehds.mabu.red/poc/persona-3d/patient.html (click the red "HbA1c 7.6 %" node, or the HbA1c line in the list). Merged in #268 and #269.

Open point for the API: this needs GET /api/patient/observations?patientId= returning a FHIR searchset, which does not exist yet; the prototype reads a static bundle.

[ma3u]

Update: time series, trend and description on all four views

What the patient view got for lab values now works for every persona through one engine helper (attachSeries): any node can carry a series, and then a click opens the right panel with the latest value, the trend against an expected band, a chart, a description and the series as a table, and unfolds the months as chained nodes on an "over time" layer at the bottom of the stack. A second click folds them. Merged in #270.

Researcher https://ehds.mabu.red/poc/persona-3d/researcher.html
Datasets I use carry my accesses per month, studies carry cumulative enrolment per quarter (mine, the IRS biomarker cohort, the MedReg respiratory cohort), and my own node carries SPE compute hours per month. Dataset and study descriptions come from the catalogue and programme records.

Health data access body https://ehds.mabu.red/poc/persona-3d/hdab.html
Participants carry accesses per month, or refused accesses for the refused applicant (band: zero expected, so the rising count is red); regulated datasets carry accesses per month; the body's own node carries the queue of pending applications at month end with a band of zero to two, which it has been above since spring.

Hospital / data holder https://ehds.mabu.red/poc/persona-3d/hospital.html
Our datasets carry accesses per month, consumers carry their accesses or refused attempts on our data, the expired quality label carries the assessor's conformance score per quarter (falling from 0.95 to 0.88, below the 0.90 renewal band), and our own node carries the volume made available per month.

Data: fictional monthly figures under ui/public/poc/persona-3d/data/*-series.json, shaped like what the Art. 73(1)(e) access log, the permit register and a study registry would yield. Each item names the node it belongs to, the measure, the unit, an optional expected band, and whether a rise is good or bad, so the same trend words mean the same thing on every view.

What this asks of the API: per-entity monthly aggregates from the access log (accesses, refusals, bytes by consumer, by dataset, by provider) and a label history. None of these endpoints exist yet; the prototypes read static files.

[ma3u]

Implementation issue opened: #271. It carries the decisions on the five questions above (add /overview, patient first, derived state computed in the API and not persisted, adopted article numbers on touch, the accessible list as the primary path with the 3D scene as an enhancement), the API contract, the page, per-persona acceptance criteria, milestones M0 to M5 and the test plan.

M0 is merged (#272) and applied on Azure: the graph now holds the data the four views need and the relations between the personas. Anna Müller (P1) treated at AlphaKlinik Berlin with 48 LOINC-coded measurements and their reference ranges, her consents to studies conducted by PharmaCo, IRS and MedReg with quarterly enrolment, 121 access events over twelve months (PharmaCo after credential expiry, Limburg without a contract, IRS refused and still attempting), and the quality label's quarterly assessments. The derivations of the prototype engine live in ui/src/lib/overview/derive.ts with 29 unit tests; journey 44 (J960 to J975) holds the acceptance cases, the route and page ones marked fixme until each milestone lands. The prototype's series files are now generated from the same figures as the seed.

[ma3u]

Shipped. The four views are product pages now: https://ehds.mabu.red/overview (persona from the role, ?persona=patient|hdab|hospital|researcher for admins), computed by GET /api/overview from the graph with the rules in ui/src/lib/overview/derive.ts, documented in docs/knowledge/apis/persona-overview.md, decision 3 recorded as ADR-040 (derived state in the API, never persisted). Issue #271 tracks the ten PRs and what is still missing (per-patient access log, Art. 77 completeness, the Art. 63 record). The prototypes above stay as the design reference.